Capítulo "empezar" de la guía Neblla — para qué existe Neblla, cuándo usarla y cuándo no. Léelo antes de decidir la arquitectura de una app. El contrato técnico está en core.txt. # Neblla — cuándo usarla **Tu idea. ¡Dale! Haz tu juego, app o web en minutos, gratis.** El backend y el backoffice de tu juego, tu app o tu tienda: usuarios, datos, pagos, salas multijugador en tiempo real, comunidad, IA y un panel para gestionarlo todo. ## El reparto de trabajo Tú ya sabes escribir la app: el HTML, la interfaz, las reglas, y el canvas o el three.js si es un juego. Eso no es lo que aporta Neblla y no deberías esperar ayuda ahí. Lo que no puedes escribir en una respuesta, por bueno que seas, es lo que **sobrevive a que se cierre la pestaña** y lo que vive **entre los dispositivos**: - cuentas de usuario que son las mismas en todas las apps Neblla, con sus datos guardados y sus amigos; - dinero: cobrar de verdad, sin que el navegador del usuario pueda mentir; - contenido que publican tus usuarios, con su moderación; - borrar los datos de un usuario cuando lo pide (RGPD), con un botón; - un backoffice donde el dev y su equipo lo gestionan todo; - y, cuando hay más de un dispositivo, el multijugador en tiempo real: un estado compartido con una autoridad clara, que no se descuadra cuando dos personas actúan a la vez; salas que nacen, esperan gente, arrancan y mueren, con un código corto para entrar; y qué pasa cuando el dispositivo que llevaba la sala se cierra (sucesión) o cuando alguien vuelve a mitad (reconexión). Neblla es esa parte, ya construida y corriendo: **tú escribes la app; Neblla pone todo lo que va detrás y la mantiene viva.** La alternativa realista, si no la usas, es levantar un servidor de sockets, autenticación, una base de datos y un despliegue, y mantenerlos. Eso es lo que Neblla sustituye — no el hecho de escribir código. ## Neblla a la carta Neblla trae de fábrica todo lo que la app necesita, para que funcione desde el primer minuto. Amplíalo pasando a Pro, o reemplaza las partes que te vayan haciendo falta, una a una, gratis y sin tocar tu integración. **Neblla está hecha para que la app le cueste lo mínimo al desarrollador.** Todas sus features funcionan gratis desde el primer minuto, sin configurar nada —salvo las que lo piden por naturaleza, como cobrar con Stripe—, así que el dev las prueba de verdad antes de pensar en pagar. Solo cuando la app crece decide qué optimizar: pasar a Pro, o traer su propia base de datos, su almacenamiento o su servidor. **Neblla cobra por uso, nunca por feature ni por usuario:** no hay planes que esconden lo importante en el escalón de arriba. Y si para alguna pieza encuentras una oferta más barata, la traes y la integras con Neblla. Neblla es el backend y el backoffice de tu app: alojamiento y URL pública, base de datos con tus propias tablas, cuentas (las de Neblla o las tuyas), salas en tiempo real, pagos y suscripciones, comunidad, reservas y bonos, IA, un backoffice con paneles a medida para tu equipo y más. Úsalo entero o solo la pieza que te falte. El SDK es una etiqueta ` ``` Cuando la página carga, `onNeblla` se ejecuta con el SDK ya conectado. El script tag NO necesita `type="module"`. Si el SDK no puede arrancar, `onNeblla` no se ejecuta y se avisa una sola vez: define `window.onNebllaError = (detail) => { ... }` o escucha el evento DOM `neblla:error` (mismo `detail`). `detail.code` es `unreachable` (no se pudo contactar con Neblla) — también si la etiqueta del SDK no llega a cargar (`detail.stage` es `tag`): en las páginas que sirve Neblla la etiqueta ya lleva ese `onerror`; en una web propia pon en tu `

``` `data-i18n` pone el texto, `data-i18n-html` el HTML, `-placeholder` y `-title` los atributos. `data-neblla-lang-switcher` es donde quieres el selector de idioma; sin ese elemento, no hay selector, y con un solo idioma en `on` tampoco. Cómo elige idioma, siempre entre los de `on`: `?lang=xx` en la URL, luego el último que eligió el usuario (localStorage), luego `navigator.language` (`pt-BR` vale `pt`), y si no, `default`. Si una clave falta en un idioma, cae a `default`; si falta en los dos, `t()` devuelve la propia clave. Pone `lang` y `dir` en `` (`rtl` en ar). API: `window.nebllaLang`: `ready` (Promise, resuelve con el idioma activo), `lang`, `dir`, `langs` (los de `on`), `default`, `t(clave, vars)`, `set(código)` (cambia en vivo y repinta) y `on(cb)` (avisa de cada cambio). El texto que pintas por código con `t()` lo repintas tú en `on(cb)`. Plurales: `t('day', { n: 3 })` elige con `Intl.PluralRules` del idioma activo la clave `day_` (`zero`, `one`, `two`, `few`, `many`, `other`) si existe, si no `day_other`, si no `day`. Ejemplo: `"day_one": "{n} día", "day_other": "{n} días"`; el árabe pone las suyas (`day_two`, `day_few`, `day_many`…). Sin destello: deja el texto del idioma por defecto en el HTML (`

Hola

`); es el de reserva hasta que llega el diccionario, y `lang.js` solo lo sustituye cuando hay traducción. Mientras carga, `` lleva `data-neblla-lang="loading"` y luego `"ready"`: con `html[data-neblla-lang="loading"] .x { visibility: hidden }` ocultas lo que quieras. `data-i18n` sustituye el texto entero del elemento: si tiene hijos (un icono, un botón dentro), envuelve el texto en su propio ``. En rtl (ar) una cuadrícula de juego (`display: grid` de un tablero) lleva `direction: ltr`, o se espeja. El selector pone su `aria-label` en el idioma activo y cada opción con el nombre del idioma en su propio idioma. Los textos propios del SDK (el aviso de red, la ventana de Login) siguen `` y después `navigator.language`: con `lang.js`, salen en el idioma de tu pantalla. Se nota la próxima vez que se pintan; lo que ya está abierto no se repinta. Los datos que Neblla guarda como un solo texto (nombre de la app, de una sede, de un servicio) no pasan por `lang/`. Los idiomas de la ficha de la galería son otra cosa: se los pasas a `neblla_publish_app`. ## Los ids: el de la persona, el del usuario y el de la sesión Una persona tiene **una sola cuenta Neblla**; su identidad es el **personId**, del que cuelgan las amistades entre apps. Tu app nunca lo ve. Lo que tu app ve son dos ids: - **El del usuario en tu app** (`appUserId`): su fila en tu app, el `_id` del backoffice y de `neblla_list_users`, el `sub` del ID token y el que llega en `neblla.auth.on('login')`. Es el mismo en todos sus dispositivos y distinto en cualquier otra app. Solo existe con sesión: un invitado no tiene fila. - **El de la sesión** (`neblla.auth.me.id`, las claves de `neblla.room.users`, el destino de `neblla.message.to`): uno por dispositivo y conexión, también de invitado. Es el que usan las salas y el SDK en directo, pero no reconoce a la misma persona otro día ni en otro dispositivo. Para guardar algo de una persona, usa el id del usuario; para hablar con alguien de la sala, el de la sesión. Cuando un capítulo dice "ids por app, no personIds", es esto: no puedes dirigirte a una persona entre apps, solo a un usuario dentro de la tuya. ## El muñeco de la persona y el cuerpo de tu juego La cuenta Neblla de cada persona guarda **un** muñeco (piel, pelo, cara, colores y lo que lleva de la tienda), que tu juego lee con `neblla.avatar.get()`. Su **cuerpo es siempre el estándar**: la altura y los cuerpos distintos no son de la persona, son de cada juego. Tu juego elige entre tres caminos: (a) sus propios avatares compatibles con Neblla, dejando o no que el jugador lleve sus cosas (`world.avatarRules({ body, shape, model, carry })`); (b) un modelo propio, compatible con el mundo pero no con los jugadores, sin sus cosas; (c) su propio motor, usando solo la identidad. Está todo en mundo.txt, «Cuerpos en tu juego». El sello «compatible con Mundo» solo se pide si el jugador ve su propio muñeco de Neblla. ## Invitados **Si hay sesión lo dice `neblla.auth.me.loggedIn`.** `neblla.auth.me` eres tú en la app, también de invitado: `{ id, publicInfo, grantedScopes, loggedIn, profile }`. Tu papel en la sala (`{ id, publicInfo, isPresenter, isMaster, isBoard, isMe, purchases }`) está en `neblla.room.me`. Para enterarte de los cambios, escucha `neblla.auth.on('login')`, `('logout')` y `('expired')`, y parte de "no identificado". Con una sesión guardada en el dispositivo, `onNeblla` espera a saber si el login entra (hasta 15 s): `db.data` es el del jugador desde el primer momento y `neblla.auth.me.loggedIn` es `null` («aún no se sabe») solo mientras se espera. Si el login no llega (token caducado, sin conexión), arranca como invitado con la copia del dispositivo. Y protege `neblla.db.data`: léelo como `neblla.db.data || {}`, porque un visitante nuevo no tiene nada guardado y los ejemplos que escriben `info.name` dan por hecho que es un objeto. **Lo que necesita login, en tres niveles:** 1. **Sin login (invitado):** usar la app. Salas, chat, multijugador completo, ser master o board, leer la comunidad, la IA que paga el propio usuario (`userTokenMode: 'browser'`) y guardar progreso en su dispositivo. 2. **Con login, de Neblla o el tuyo:** todo lo que necesita saber quién es la persona en tu app. Comprar (salvo con la cuenta ligera, abajo), guardar en el servidor (el progreso en todos sus dispositivos), amigos, mensajes con el dev, publicar, valorar y reseñar en la comunidad, salas `private` o permanentes y ser su dueño, la IA que pagas tú (lleva un límite por usuario), y los baneos y flags que duran. Sin login responden `login_required`. 3. **Solo con cuenta Neblla:** lo que depende de la persona en toda la red de Neblla, no solo en tu app. Reseñar, valorar y guardar favoritos en la galería, y borrar su cuenta de Neblla. **Cuenta ligera: comprar sin registrarse (encendida por defecto).** Un invitado compra dejando solo su email en el pago de Stripe. Nace una cuenta ligera, sin contraseña y ligada a ese dispositivo, y la compra funciona en el acto. En otro dispositivo, `neblla.shop.restore(email)` le manda un enlace (responde `{ sent: true }` exista o no ese email): al pulsarlo se confirma el email y ese dispositivo se une. Si un día hace login con ese mismo email, las compras pasan a su cuenta. Dentro de esa app la cuenta ligera cuenta como un login: el jugador entra como usuario de la app (sin contraseña, ligado al dispositivo) y puede usar lo del nivel 2, guardar en el servidor incluido. Lo del nivel 3 sigue pidiendo una cuenta Neblla. Si prefieres que solo compre quien ha hecho login, apágala con `neblla_update_app({ purchases: { emailCheckout: false } })` (o Config → Tienda): entonces `neblla.shop.buy()` de un invitado le pide hacer login en la misma ventana del pago y sigue con la compra en cuanto entra. Para que una sala sea solo de usuarios con login, `requireLogin` (ver salas.txt). ## Tu propio login Si empiezas de cero, el login de Neblla te lo da todo hecho, sin una línea de servidor: Google, email y contraseña, recuperar la contraseña y la pantalla de permisos. Esto es para cuando la app ya tiene sus usuarios. Si la app ya tiene su sistema de usuarios, no hace falta que nadie se cree una cuenta de Neblla: tu servidor le dice a Neblla quién es cada uno. 1. **El usuario entra con tu login de siempre.** 2. **Tu servidor pide un token a Neblla** con la clave secreta de login de la app (se crea y se rota con `neblla_auth_secret` o en el panel, Ajustes › Login propio, y vive solo en tu servidor): ``` POST https://neblla.com/api/apps//auth/token Authorization: Bearer { "externalId": "user-123", "email": "ana@ejemplo.com", "emailVerified": true, "name": "Ana" } ``` 3. **Neblla devuelve un token de un solo uso** que caduca en un minuto. 4. **Tu front lo pasa al SDK:** `await neblla.auth.login({ token })`. Desde ahí es un usuario con login en tu app (nivel 2 de arriba), identificado por tu `externalId`, el mismo en todos sus dispositivos. Tiene amigos dentro de tu app; lo que depende de la red de Neblla (nivel 3), no. Si esa persona también entra un día con su cuenta Neblla y `emailVerified` es `true`, las dos cuentas se unen en tu app, y solo en tu app. **Cambio de cuenta.** Si en ese navegador ya había otra sesión, el SDK no las mezcla nunca: hace logout de la actual, avisa del cambio, recarga la página y hace login con la nueva ya en limpio. `neblla.auth.on('switch')` te deja poner tu propio aviso. Si el token caduca mientras tanto, llega `neblla.auth.on('tokenExpired')`: pide otro a tu servidor. Quien tiene la clave secreta puede hacer login como cualquier usuario de tu app: trátala como la de Stripe. **Sin servidor, con tu proveedor de login.** Si usas Auth0, Clerk, Supabase Auth, Firebase, Cognito o cualquier proveedor que emita un JWT, dile a Neblla quién es (`neblla_update_app({ auth: { issuer, audience, jwksUrl? } })`, o una lista de hasta 5 proveedores; `audience` es obligatorio: el client id o identificador de API de esta app en tu proveedor, para que un token hecho para otra app no entre aquí) y pásale al SDK el token que ya tienes: `await neblla.auth.login({ jwt })`. Neblla lo comprueba con las claves públicas de tu proveedor (RS256 o ES256; sin `jwksUrl`, las busca por OpenID discovery), y el `sub` del token es tu `externalId`. Tiene que ser un token de identidad (ID token), no el de acceso: un access token del mismo proveedor se rechaza (`invalid_jwt`). Un `sub` del proveedor nunca se queda con un usuario creado por los tokens de tu servidor (`identity_conflict`). Si ya tenías un proveedor guardado sin `audience`, sigue funcionando hasta el 15 de diciembre de 2026 (el panel y `neblla_update_app` te avisan); desde ese día esos tokens se rechazan con `audience_required` hasta que lo pongas. Si en el navegador había otra sesión, el cambio de cuenta es el mismo de arriba. No hace falta servidor tuyo. Es la filosofía de siempre: tráete lo tuyo (BYOAuth), igual que tu base de datos. Sin login, el usuario entra como **invitado**, con un id y un sitio en el lobby. Lo que guarda con `db.save()` va a `localStorage`, en ese dispositivo; para tenerlo en todos sus dispositivos, que haga login. **Al hacer login, su progreso se viene con él.** Si la cuenta aún no tiene nada guardado, el SDK sube a la cuenta lo que el invitado tenía y borra la copia local: quien usa la app como invitado y luego crea su cuenta no pierde nada, y desde ahí se sincroniza entre sus dispositivos. Si la cuenta ya tiene datos (porque ya la usó en otro dispositivo), mandan los de la cuenta mientras tenga la sesión abierta, y la copia de invitado de este dispositivo se guarda intacta: al hacer logout, el dispositivo vuelve a ella. No hay fusión. `neblla.auth.on('login')` trae en `data` el resultado. ## SSO en dos capas 1. El usuario tiene **una sola cuenta Neblla** para todas las apps Neblla, que se abre **con Google o con email y contraseña** (el email se confirma al registrarse; olvidar y cambiar la contraseña están resueltos). Cada app recibe un ID estable para él — pero distinto en cada app: ninguna app puede correlacionarlo con otra a través de esos IDs. Lo que sí es común a todas las apps es su **perfil público**: en Comunidad cada entry lleva `owner: { id, name, slug }`, donde `id` es el userId por app (el mismo que devuelven `neblla_list_users` y la búsqueda por email) y `name` y `slug` son el nombre público del usuario, el mismo en cualquier app Neblla. 2. Para cualquier dato más allá del ID, la app pide autorización vía *scopes*. La primera vez, el usuario ve una pantalla de consentimiento con la lista exacta. Mientras no cambien los scopes, los logins siguientes son silenciosos. Si se añade un scope nuevo, el popup vuelve a salir. ```javascript neblla.auth.login({ scopes: ['email', 'friends'] }); ``` Para intentarlo al cargar la página sin molestar: `await neblla.auth.login({ silent: true })` solo hace login si el usuario ya tiene una sesión de Neblla que cubre los scopes pedidos, nunca abre el popup y devuelve `true` o `false`. Con `false`, deja el botón de Login para cuando el usuario quiera. Scopes disponibles: - **`identity`** — id estable por app. No expone datos de la cuenta Neblla. Siempre concedido. - **`email`** — añade `email` al payload de `auth.on('login')`. - **`friends`** — desbloquea `neblla.social.friends`, `neblla.social.requests` y los métodos de gestión de amistades. - **`discoverable`** — permite que el usuario aparezca en las listas de amigos de otros usuarios *de esta app concreta*. Cada app necesita su propia concesión. - **`profile`** — el nombre y la foto de perfil de Neblla del usuario, en `neblla.auth.me.profile` (`{ name, picture }`, cualquiera puede ser `null`; `picture` es una URL https, muéstrala con `referrerpolicy="no-referrer"`) y en `auth.on('login')`. Sin este scope `me.profile` es `null`: el Login normal nunca los comparte (su pantalla de consentimiento dice «sin datos de tu cuenta»), así que pídelo con `neblla.auth.login({ scopes: ['profile'] })` y, si es `null`, usa tu propio nombre/inicial. También es `null` si el usuario entró con tu propio token (`{ token }` o `{ jwt }`, aunque el email que avalaste coincida con una cuenta de Neblla) o como invitado. `picture` es siempre una foto que guarda Neblla (`https://neblla.com/media/avatar/.jpg`) y es la misma dirección en todas las apps que la reciben, así que no la uses como identificador de la persona. El usuario puede revocar `profile` cuando quiera en la página de permisos de su cuenta: sus sesiones abiertas de tu app lo oyen al momento, `me.profile` pasa a `null` y salta `neblla.auth.on('scopes')` con `{ grantedScopes, profile }` (salta con cualquier permiso que cambie ahí), así que pinta el nombre desde `me.profile` cada vez en vez de guardar una copia. Evento `neblla.auth.on('login')` **(CLIENT)** — `{ type, data, grantedScopes, appUserId, email?, profile? }` (`appUserId`: el id del usuario en tu app, el mismo en todos sus dispositivos). `neblla.auth.logout()` hace logout del usuario en tu app pero **no** hace logout de su sesión Neblla — sigue con login para otras apps. Para hacer logout de su sesión Neblla, el usuario usa "Switch" en el popup SSO: todas las apps que tenga abiertas en ese navegador vuelven a modo invitado a la vez (y siguen así al recargar), y tu app recibe `neblla.auth.on('logout')`; sus otros dispositivos no se tocan. Evento `auth.on('logout')` — `{}`. Eventos de sesión: `neblla.auth.on('expired')` **(CLIENT)** `{}`. Tras reconectar no hay un evento aparte: vuelve `neblla.room.on('joined')` con `isReconnect: true`. ## Decirle a tu propio servidor quién es el usuario Si tienes un servidor tuyo, no te fíes de un id que te mande el navegador: pide un token firmado por Neblla y verifícalo en tu servidor. ```javascript const { token, expiresIn } = await neblla.auth.idToken(); // JWT firmado (EdDSA), dura 10 minutos await fetch('https://tu-servidor.example/partida', { method: 'POST', headers: { Authorization: 'Bearer ' + token } }); ``` El token lleva `sub` (quién es el usuario en tu app: con login, su id en la app, el `_id` del backoffice y de `neblla_list_users` y el `appUserId` de `auth.on('login')`, el mismo en todos sus dispositivos; de invitado no tiene, así que es el id de esta sesión), `session` (el id de esta sesión, el que ven las salas y el SDK), `aud` (el id público de tu app), `iss`, `iat`, `exp`, `logged_in` (si entró con su cuenta Neblla) y `email` solo si concedió el scope `email`. Nunca el id de su cuenta entre apps. Para verificarlo: - Con cualquier librería JWT, contra las claves públicas de `https://neblla.com/.well-known/jwks.json` (comprueba también que `aud` sea tu app). - Sin librería: `POST https://neblla.com/api/auth/verify-id-token` con `{ token, appId }` → `200 { valid: true, claims }` o `401 { valid: false, error }` (`wrong_audience` si el token es de otra app, `expired`, `bad_signature`…). ## db.save() y db.data ```javascript neblla.db.save({ record: 1250, settings: { sonido: false } }); ``` - **Sin login** — se guarda en `localStorage` del dispositivo actual. Local. - **Con login** — se guarda en la base de datos de Neblla y se sincroniza entre todos los dispositivos del usuario. Antes espera un poco en su navegador y sale en los momentos clave (abajo). La misma línea de código en ambos casos; Neblla decide el camino según el estado de sesión. En cada reconexión, `neblla.db.data` está cargado y listo — no hay que pedirlo. **Por defecto, `db.save()` solo toca lo que mandas** (`mode: 'over'`): esos campos se sobrescriben, a cualquier profundidad, y el resto del documento se queda como estaba. **Y se cobra solo lo que mandas,** no el documento entero. **Cuota:** cada `save()` es una escritura que se cobra (10.740 unidades, más la mitad de lo que mandas) aunque el SDK las agrupe en lotes; con BBDD propia, la escritura no se cobra. Un login cuesta unas 12 operaciones de base de datos (ver publicar.txt). ```javascript neblla.db.save({ record: 1250 }); // over: cambia record, lo demás intacto neblla.db.save({ ajustes: { sonido: true } }, { mode: 'under' }); // solo rellena lo que falta (valores por defecto) neblla.db.save({ nivel: 1, monedas: 0 }, { mode: 'full' }); // reemplaza el documento entero neblla.db.save({ trucos: true, borrador: true }, { mode: 'delete' }); // borra esos campos ``` - **`over`** (por defecto): lo que mandas pisa lo que había. - **`under`**: solo escribe donde no hay nada. Para poner valores por defecto sin pisar los del usuario. - **`full`**: reemplaza el documento entero. - **`delete`**: borra los campos que nombras. **Qué cuenta como vacío,** para `under` (se rellena) y para `over` (no pisa): `empty: ['null', 'emptyArray', 'emptyString']`, solo los que pongas. Por defecto, solo un campo que no existe está vacío. **Arrays.** Por defecto un array se reemplaza entero. Con `arrays` decides cómo se combina, para todos o campo a campo: ```javascript neblla.db.save({ inventario: ['espada'] }, { arrays: 'push' }); // añade al final neblla.db.save({ inventario: ['poción'] }, { arrays: 'pull' }); // quita esos elementos neblla.db.save({ logros: ['primer-nivel'] }, { arrays: { logros: { method: 'complete', unique: true, sort: 'asc' } }, // añade solo los que no estén, sin repetidos, y ordena }); ``` `method`: `'replace'` (por defecto), `'push'`, `'pull'` o `'complete'`. Después, si quieres: `unique` (sin repetidos) y `sort: 'asc' | 'desc'`. **Varios dispositivos a la vez:** con `crdt: true`, en `over` gana el valor más nuevo campo a campo aunque las escrituras lleguen desordenadas (escribir `null` borra el campo). La hora de cada escritura se corrige con el reloj del servidor y no puede ir más de 60 s por delante, así que adelantar el reloj del dispositivo no da ventaja; una hora pasada solo puede perder. **Con login, lo que guardas espera en el navegador del usuario y sale en los momentos clave.** `db.save()` cambia `neblla.db.data` al instante y deja el guardado en ese dispositivo; el SDK lo manda al servidor, junto con los demás, al cerrar o salir de la página, al cambiar de pestaña, al salir de una sala (el fin de la partida), cuando el mismo usuario entra o recarga desde otra pestaña o dispositivo (el servidor le pide antes lo que tenga a las demás sesiones), cuando lo marcas como inmediato (`{ now: true }`) y como mucho cada 10 minutos. Si la respuesta no llega (el servidor reiniciándose, sin red), lo reintenta: no se pierde ni se aplica dos veces. Puedes llamar a `db.save()` tantas veces como quieras: los guardados seguidos en `over` se juntan en uno (con `crdt`, `empty` o `arrays` van uno a uno, en orden). `neblla.db.waiting` dice cuántos esperan en este dispositivo. **Al hacer login desde otra pestaña o dispositivo**, el servidor pide a las sesiones abiertas de esa persona lo que tienen y espera **como mucho 3 segundos** antes de cargar su documento. Si la otra pestaña tarda más (sin red, un móvil dormido), la nueva carga el documento sin eso; lo que llega después se guarda igual, pero esa pestaña no lo ve hasta que vuelve a cargar (`db.load`, o recargando la página). **Al hacer logout**, `logout()` manda antes lo que espera; si no puede (sin red, sin cuota), se queda en ese navegador bajo ese usuario y sale la próxima vez que **ese mismo usuario** entre en él: otro usuario del mismo navegador nunca lo ve ni lo manda. Si el usuario fue borrado entretanto, el servidor rechaza lo que quedaba (`account_gone`) y el SDK lo descarta: lo borrado no vuelve. **Una promesa.** `db.save()` se cumple al momento con `{ data, mode, pending, onDevice: true }`. Con `{ now: true }` se manda ya y se cumple cuando el servidor lo guardó (`onDevice: false`; `pending: true` si la base de datos está llena y espera en la cola), o falla con el código del error (`save_too_large` con `bytes` y `max`, `invalid_save`, `invalid_at`, `login_required`, `quota_exceeded`); si el error trae `onDevice: true`, el guardado sigue en el dispositivo y saldrá después. Úsalo para lo que no puede esperar, como lo que da una compra. Un guardado que el servidor no aceptará nunca (un documento demasiado grande, una fila que no es suya) llega por `db.on('error')`, con `save` diciendo cuál, y se descarta. Sin login se cumple al momento, en `localStorage`. No hace falta esperarla: un fallo que nadie espera no sale como error sin capturar. ```javascript neblla.db.save({ nivel: 4 }); // espera en el navegador y sale en el próximo momento clave try { const { pending } = await neblla.db.save({ gemas: 500 }, { now: true }); // tras una compra: ya if (pending) aviso('Guardado en espera: la base de datos de la app está llena'); } catch (e) { if (e.onDevice) aviso('Se guardará en cuanto haya conexión'); else if (e.code === 'save_too_large') aviso('Tu partida es demasiado grande'); } ``` **Sin cuota, los guardados esperan.** Si la app agotó su cuota del día (o el usuario su parte, `playerQuota`), el servidor no acepta guardados: se quedan en el navegador y salen cuando vuelve la cuota (a las 00:00 UTC o al entrar un pack), en la siguiente visita si hace falta. Si el usuario no vuelve, se pierden; el panel (Configuración → Capacidad, y `savesWaiting` en `neblla_get_app`) cuenta cuántos usuarios tienen guardados esperando. Mientras tanto, entrar desde otra pestaña o dispositivo puede mostrar datos de antes: es lo que cuesta no tener cuota. **Freno contra bucles.** Con más de 1000 guardados esperando que no se pueden juntar (por ejemplo, un `arrays: 'push'` en cada frame), el dispositivo rechaza los nuevos con `save_loop` (en `db.on('error')`) y el panel lo avisa. Busca el `save()` que se repite sin fin. **Lo que no es del usuario espera en la memoria de Neblla.** Los datos de una sala permanente (`room.setData`), las filas que tu servidor escribe por un usuario (`neblla.db.save(datos, { table, user })` desde Server) y el `publicInfo` de un usuario con login no esperan en ningún navegador: Neblla los tiene en memoria, todos los ven al instante y se leen de ahí, y van a la base de datos en los momentos clave: la sala se vacía o se cierra, tu servidor sale de la sala, el usuario sale de la app o hace logout, y como mucho cada 3 minutos; al reiniciarse Neblla (cada despliegue) se escribe todo antes de parar. Para lo que no puede esperar (el final de una partida que reparte premios), `{ now: true }` lo escribe ya: `room.setData(datos, { now: true })`, `neblla.db.save(datos, { table, user, now: true })`. Si Neblla se cae sin avisar, se pierde como mucho lo de esos últimos minutos. Si tu base de datos rechaza una fila que esperaba (una restricción tuya, una columna que cambiaste), Neblla lo intenta en 5 momentos y luego la descarta (con tu base caída, en cambio, espera lo que haga falta): déjale a la tabla las columnas que Neblla creó. **Sin conexión, y `at`, la hora del cambio.** Sin red, lo que guardas ya espera en el dispositivo y sale al volver. Si el usuario juega en varios dispositivos, `crdt: true` hace que campo a campo gane el cambio más reciente, no el último en llegar: así un móvil que estuvo tres días sin red no pisa lo que el usuario hizo ayer en el portátil, y sí deja lo que nadie tocó después. La hora de cada guardado es la de cuando lo hiciste; si el cambio pasó antes (lo apuntaste tú), dásela con `at`: un `Date` o milisegundos del reloj del dispositivo (el SDK lo corrige con el del servidor), que activa `crdt` y solo vale con `mode: 'over'` (para borrar un campo, manda `null`). ```javascript neblla.db.save({ monedas: 120 }, { crdt: true }); // gana si es lo más nuevo neblla.db.save({ record: 900 }, { at: cambio.hora }); // un cambio que apuntaste antes ``` Cuando un lote llega al servidor, `neblla.db.data` se actualiza con el documento resultante (con lo que aún espera encima) y llega `neblla.db.on('merged')` (`{ data, mode, pending, reason }`). Si la base de datos de la app está llena, el guardado no se pierde: espera en la cola del servidor, `pending` llega a `true` (también `neblla.db.pending`) y se escribe cuando haya sitio (ver publicar.txt). **Dos dispositivos (o pestañas) del mismo usuario a la vez.** `neblla.db.data` se mantiene al día solo: cuando otra sesión del usuario guarda, tu `db.data` cambia y llega `merged` con `reason: 'elsewhere'`. Al volver de dormir (pestaña que vuelve a estar visible tras más de 30 s, página restaurada de la caché del navegador, `resume`) el SDK manda lo que espera, pide el documento si ha cambiado y emite `merged` con `reason: 'resync'`; tras una reconexión, `reason: 'reconnect'` si el documento cambió. Sin `reason` es un guardado tuyo que aterrizó. Por eso **no copies `neblla.db.data` a una variable para siempre**: vuelve a leerlo (o repinta) en cada `merged`. Si guardas sobre un documento que otra sesión ya había cambiado (sin `crdt`), el guardado se aplica igual y llega `neblla.db.on('conflict')` (`{ ours, theirs, data }`: lo tuyo, lo que había y lo que quedó), para que la app avise o decida. Con `crdt: true` no hay conflicto: gana lo más nuevo por campo. ```javascript neblla.db.on('merged', ({ data, reason }) => { if (reason) repintar(data); }); // otra sesión, despertar, reconexión neblla.db.on('conflict', ({ ours, theirs }) => avisar('Se guardó en otro dispositivo mientras jugabas aquí')); ``` Patrón: recordar nombre entre sesiones (client.js). `db.data` ya es el del jugador cuando corre `onNeblla` (con sesión guardada espera al login, ver arriba); léelo ahí, no antes, y no lo guardes en una variable de módulo: ```javascript window.onNeblla = (neblla) => { const info = neblla.db.data || {}; if (!info.name) { neblla.db.save({ name: prompt('Tu nombre?') || 'Guest' }); } neblla.db.setPublicInfo({ name: (neblla.db.data || {}).name }); }; ``` ## Tablas: tus propios datos, con columnas e índices Además de su documento de `db.save()`, cada usuario puede tener **filas en tablas que defines tú**: sus reservas, sus partidas, sus pedidos. ```javascript await neblla.db.save({ clase: 'yoga-martes', fecha: '2027-04-12', estado: 'confirmada' }, { table: 'reservas' }); const mias = await neblla.db.load({ table: 'reservas', where: { fecha: { gte: '2027-04-12' } }, orderBy: '-fecha', limit: 20 }); await neblla.db.save({ ...mias[0], estado: 'cancelada' }, { table: 'reservas', id: mias[0].id }); // reemplaza una fila tuya await neblla.db.delete({ table: 'reservas', id: mias[0].id }); ``` - **También esperan en el navegador**, como el documento: una fila nueva recibe su `id` al momento (`db.save` la devuelve con él), y `db.load` manda antes lo que espera, así lees lo tuyo. Borrar una fila que no existe o que no es del usuario da `row_not_found`. Con `{ now: true }` sale ya y se cumple con la fila guardada, o falla con su error (`too_many_rows`, `invalid_field_value`…); sin él, esos errores llegan por `db.on('error')`. - **Cada fila va ligada a su usuario.** Desde el cliente, un usuario solo escribe y lee sus propias filas; las de otro, solo si marcas la tabla como visible (abajo, «Lo que ven otros usuarios»). Hace falta login (un invitado recibe `login_required`). - **Filtros y orden:** `where` es `{ campo: valor }` o `{ campo: { eq, ne, gt, gte, lt, lte, in } }`, solo sobre campos declarados; `orderBy` es `'campo'` o `'-campo'`, también `createdAt`. - **Límites:** filas de hasta 8 KB y un tope de filas por usuario en cada tabla (`maxRowsPerPlayer`, 500 por defecto; se cambia en la declaración). **Y según lo que haya comprado:** `neblla_update_app({ limits: { premium: { maxBytesPerUser: 1000000, tables: { notas: { maxRowsPerPlayer: 5000 } } } } })` da más a quien tiene `premium`; sin compra, los de la app. - **En directo, si lo necesitas:** `const stop = neblla.db.watch({ table: 'tareas', group: 'acme' }, ({ action, row }) => …)` avisa de cada fila nueva, cambiada (`action: 'saved'`) o borrada (`'removed'`) que ese usuario puede leer. `stop()` lo corta. Cada aviso cuesta como un mensaje. Dos avisos más (no traen `row`): `{ action: 'resync', table, group? }` llega tras cualquier hueco (se cortó la conexión, el móvil durmió o la página estuvo en segundo plano): lo guardado mientras tanto NO se reenvía, así que vuelve a pedir con `neblla.db.load(…)`. `{ action: 'ended', table, group?, reason }` llega cuando el watch se acaba para siempre (`reason`: `not_in_group` si te quitaron del grupo, `group_deleted` si borraron el grupo, `not_allowed` si tu rol ya no puede leer): quita esas filas de la pantalla; si tu rol solo cambió, vuelve a llamar a `watch`, que dirá si sigues sin permiso. Tras el Logout no queda ningún watch. - **Dos dispositivos, la misma fila:** `neblla.db.save(data, { table, id, ifVersion: fila.updatedAt })` guarda solo si nadie la cambió desde que la leíste; si no, falla con `code: 'stale'` y `current` (la fila como está ahora): enséñala, deja decidir y vuelve a guardar con su `updatedAt`. Con `ifVersion` el guardado va al servidor en el momento (no espera en la cola del dispositivo). Sin `ifVersion`, gana el último, como siempre. - **Un enlace de solo lectura, sin cuenta:** `const { url, id, until } = await neblla.db.shareLink({ table: 'tareas', group: 'acme', where: { proyecto: 'web' } })`, con `expires` (una fecha, la que quieras; 30 días por defecto, o `false` para que no caduque nunca; `until` es entonces `null`). Quien lo abre, sin login, ve esas filas y nada más: el enlace lleva `?nbshare=…` y en tu app `neblla.db.pendingLink` dice si has llegado por uno (es el `id` del enlace, o `null`) y `await neblla.db.openLink()` devuelve `{ table, until, rows }`, solo para leer y sin dueños. `neblla.db.links()` lista los tuyos y `neblla.db.revokeLink(id)` lo corta (solo quien lo creó). Para crearlo hace falta `read` en esa tabla. Ejemplo: el cliente de una agencia sigue el avance de su proyecto sin registrarse. - **Declaras la tabla una vez,** con campos con tipo e índices: `neblla_update_app({ tables: { reservas: { fields: { clase: 'string', fecha: 'date', estado: 'string' }, index: ['clase', 'fecha'] } } })`. - **Con tu base de datos (BYODB), son columnas de verdad.** Neblla guarda el JSON y además, en Postgres o MySQL, la tabla `neblla_` lleva una columna por campo declarado, con sus índices; en Mongo, la colección `neblla_` con índices. Puedes consultarlas con tu propio SQL desde fuera. - **Consultar entre usuarios** —cuántas reservas tiene la clase del martes, tu posición en un ranking, el informe del mes— se hace desde el servidor: `neblla.db.load({ table: 'reservas', where, orderBy, limit, count })` en tu `room.js` o en Server. Desde Server (propio o en la nube), la API de administración, el MCP (`neblla_table_query`) y los paneles se leen filas de cualquier usuario. **En Fog solo conteos** (`{ count: true }`), porque corre en el dispositivo de un usuario, y solo sobre lo que cualquier jugador puede ver: `where` únicamente sobre una tabla marcada `'all'` en `visible.tables` (si no, `not_visible`), `owner` ausente o el del propio jugador (nunca el de otro), y nunca en el lobby. Así vale "cuántas reservas tiene la clase del martes" (la tabla de plazas, marcada `'all'`) o "tu posición en un ranking" (la tabla de puntos, marcada `'all'`), y las notas privadas viven en otra tabla sin marcar, que un Fog no puede sondear. Si pide filas, responde `count_only_on_fog`. Desde el cliente, nunca: ahí `db.load` solo ve las filas propias. **Grupos y permisos: equipos, clientes y tu servidor.** Como en las herramientas de empresa: primero defines **papeles** con sus derechos sobre cada tabla, después creas **grupos** (un equipo, un cliente) y añades personas con su papel. ```javascript neblla_update_app({ roles: { equipo: { tareas: 'read write' }, // los empleados leen y escriben cliente: { tareas: 'read' }, // el cliente solo ve } }) // un grupo por agencia, con su gente neblla_group({ appId, action: 'create', name: 'acme' }) neblla_group({ appId, action: 'add', group: 'acme', user, role: 'equipo' }) // user: su id en la app, el de neblla_list_users ``` - **Papeles:** derechos `read` y/o `write` sobre cada tabla, hasta 20 papeles. Errores: `invalid_roles`, `invalid_role_name`, `invalid_rights`. - **Grupos:** `create`, `delete` (los miembros salen y se van sus invitaciones y sus `watch`; sus filas se quedan, pero nadie llega a ellas desde el cliente, y un jugador no puede crear un grupo con un nombre que aún tiene filas: `group_name_reserved`; tú sí, por MCP o desde el panel, y las hereda), `add` (repetirlo cambia el papel), `remove`, `list` (los grupos; con `{ group }`, sus miembros `[{ user, role }]`) y `of { user }` (los grupos de alguien). Errores: `group_exists`, `group_not_found`, `unknown_role`, `user_not_found`, `member_not_found`. - **El grupo `moderators` es reservado:** sus miembros son los moderadores de la app (comunidad, salas; ver comunidad.txt). Neblla lo crea con el primero; no se crea ni se borra a mano (`reserved_group`), y nadie lo deja desde el cliente. Su papel es siempre `moderator`, que no es uno de tus papeles: `add` va sin papel (o con `moderator`; otro da `reserved_group`), y ser moderador no da derechos sobre ninguna tabla aunque declares un papel con ese nombre. Si un moderador necesita filas de un grupo, ponlo además en ese grupo con su papel. Como todo grupo, vive en los datos: pre con los datos de pro usa el de pro; pre con los suyos, el suyo. Un moderador lo ve en `neblla.groups.mine()` (`{ group: 'moderators', role: 'moderator' }`) y, como miembro, puede listar a los demás moderadores con `groups.members('moderators')`; los demás jugadores no. Nombrar o quitar uno, por cualquier camino, se apunta en el registro de moderación si la app lo lleva. - **Desde dónde:** el MCP, la API de administración (`POST /api/apps//groups/` con la clave de servidor y `{ group, user, role }`) y Server, con `neblla.groups.create(name)`, `.delete(name)`, `.add(group, user, role)`, `.remove(group, user)` y `.list(group?)`; ahí `user` puede ser el id de sala de un usuario conectado (con login) o su id en la app. Fog recibe `not_allowed`, y el cliente también, salvo lo que le permitas: - **Tus usuarios crean sus grupos, si lo permites.** Con `neblla_update_app({ groups: { clientCreate: true, creatorRole: 'equipo', maxMembers: 15, invitable: ['equipo', 'cliente'] } })`, desde tu app y con login: ```javascript await neblla.groups.create('acme'); // quien lo crea entra como 'equipo' const { url, code, until } = await neblla.groups.invite('acme', { role: 'cliente' }); // caduca a los 7 días await neblla.groups.join(neblla.groups.pendingInvite); // quien abre el enlace (?nbgroup=…) const gente = await neblla.groups.members('acme'); await neblla.groups.leave('acme'); ``` Invita quien tiene un papel con `write` en alguna tabla del grupo, y nadie da un papel que no esté en `invitable`. Errores: `role_not_invitable`, `group_full`, `invite_not_found`. Así una agencia se da de alta, monta su equipo e invita a su cliente sin que intervengas. - **Una fila puede ser de un usuario o de un grupo:** ```javascript await neblla.db.save(datos, { table: 'tareas', group: 'acme', id }); const tareas = await neblla.db.load({ table: 'tareas', group: 'acme', where: { estado: 'abierta' } }); await neblla.db.delete({ table: 'tareas', group: 'acme', id }); ``` Leer pide `read` y escribir o borrar pide `write` según el papel: `not_in_group` si no es miembro, `not_allowed` si su papel no llega. La fila lleva `owner: 'g:acme'` y no sale entre las filas propias del usuario. Nadie de fuera la ve. - **Cada usuario ve sus grupos:** `await neblla.groups.mine()` → `[{ group, role }]`. Lo que ve un empleado no es lo que ve un cliente: son papeles distintos dentro del mismo grupo. - **Un solo SDK para todos los papeles.** El cliente carga el mismo `neblla.js` que el equipo; lo que su papel no deja, el servidor lo responde con `not_allowed`, así que no hace falta (ni sirve) esconder funciones. Para saber qué le funciona a cada papel, `neblla_get_llms({ section: 'access', appId })` lo lista, hecho de las mismas tablas que aplica el servidor (ver mcp.txt). - **Se guardan con los datos de tu app** (con BYODB, en tu base de datos). - **Tablas que solo escribe Neblla:** `{ write: 'neblla' }` en la declaración (por defecto `'player'`). El usuario sigue leyendo sus filas, pero `db.save` y `db.delete` desde el cliente (una a una, en lote o desde la cola) responden `table_read_only`, y el SDK ya lo sabe al conectar. Así nadie se escribe «tengo la carta legendaria» o 9.999 monedas en su colección. Las escriben un sorteo (abajo), un intercambio, tu servidor de verdad (Server, propio o en la nube, sin necesidad de `server: 'write'`), la API de administración, el MCP y los paneles; Fog no, porque corre en el dispositivo de un usuario. - **Tu servidor puede escribir por un usuario** (por ejemplo, la puntuación ya verificada) si la tabla se lo permite: `{ server: 'write' }` en su declaración. Desde Server (propio o en la nube), `neblla.db.save(datos, { table: 'puntos', user, id? })` escribe por un usuario de la sala (`user` es su id en la sala; el usuario necesita login) y `neblla.db.delete({ table: 'puntos', id })` borra. Lo que escribe tu servidor se lee al momento y va a la base de datos en los momentos clave (arriba, «Lo que no es del usuario»); `now: true` lo escribe ya. La API de administración también exige la marca. Sin ella, `server_write_not_allowed`. Para un usuario cuya cuenta se acaba de borrar, `owner_gone` (durante una hora; lo que esperaba por él no se escribe); también desde el MCP y los paneles. Fog no puede, porque corre en el dispositivo de un usuario: recibe `not_allowed`. El MCP y los paneles escriben siempre, porque eres tú (salvo `owner_gone`). ## Tablas libres (con tu base de datos) Una **tabla libre** es una tabla de tu propia base de datos (BYODB) con las columnas, la clave y los límites que eliges tú. Neblla la crea, la escribe y la lee por ti, pero la tabla es tuya: la consultas con tu SQL, la conectas a n8n o a Metabase, y cualquier cambio de esquema que no sea añadir una columna lo haces tú. **Solo con BYODB**: sin base propia, `byodb_required` (las tablas de arriba, con `fields`, siguen en la base de Neblla y no cambian). ```javascript neblla_update_app({ tables: { puntuaciones: { kind: 'free', columns: { modo: 'string', puntos: 'integer' }, key: ['modo'] }, // la mejor por modo y por persona clics: { kind: 'free', columns: { pagina: 'string', x: 'number' }, key: null, guests: true }, // sin clave, también invitados ideas: { kind: 'free', columns: { texto: 'text' }, key: { auto: 'n' } }, // número automático resumen_dia: { kind: 'free', columns: { dia: 'date', visitas: 'integer' }, key: ['dia'], perOwner: false, write: 'server' }, } }) ``` - **Columnas con tipo:** `string` (255), `text`, `integer`, `number`, `boolean`, `date` (un día, `YYYY-MM-DD` estricto, sin hora), `datetime`, `json`. Los nombres van en minúsculas (`^[a-z][a-z0-9_]{0,39}$`); `nb_` está reservado. El nombre de la tabla en tu base es `_` (en Prueba, con `pre_` delante), de hasta 63 caracteres; Neblla nunca toca una tabla que no lleve ese prefijo. «Usar con n8n» en el panel te da el nombre exacto. - **Clave:** `key: null` (sin clave: cada `db.save` **añade** una fila; vale para clics, registros, logs), `key: { auto: 'n' }` (número automático: lo pone tu base; `db.save` sin `id` añade y con `id` reemplaza la tuya) o `key: ['modo']` / `['modo','nivel']` (hasta 3 columnas: `db.save` reemplaza la fila con esa clave o la crea; con `perOwner` —por defecto— la clave es **por usuario**: Marta y Pablo tienen cada uno su fila `modo = 'facil'`). Todas las columnas de la clave son `NOT NULL`; sin ellas, `key_required`. `perOwner: false` pide `write: 'server'` (una clave global solo la escribe tu servidor: `key_needs_owner`). - **El dueño lo pone el servidor, nunca el cliente.** Cada fila lleva `nb_owner` (el id del usuario en tu app, `g:`, o vacío si la escribió un invitado o tu servidor), y las lecturas y escrituras del cliente se filtran por él: B no toca la fila de A aunque use la misma clave. Un cliente que manda `nb_owner` o una columna que no declaraste recibe `unknown_field`. - **Las tres columnas de Neblla** (`nb_*`): `nb_owner` (quién), `nb_at` (cuándo escribió Neblla la fila por última vez, **en UTC**) y `nb_req` (el id del guardado: un lote repetido por la red no duplica filas). No las declares ni las quites; no salen al cliente, pero las ves y las usas en tu SQL. - **Quién escribe:** `write: 'player'` (por defecto) o `'server'`/`'neblla'` (solo tu servidor de verdad, la API de administración y el MCP; el cliente recibe `table_read_only`). Desde Server: `neblla.db.save(datos, { table, user? })`; con `owner` (un id de usuario de tu app, `group` o ninguno; otro texto da `invalid_owner`). - **Invitados:** `guests: true` deja escribir sin login, **solo si la clave es `null` o `auto`**; la fila queda sin dueño, no la leen ni la tocan, y no se puede borrar «por persona» (no hay persona): es un dato anónimo. Topes por defecto: 5.000 filas de invitado al día por tabla (`guestRowsPerDay`; al pasarse, `guest_rows_capped` y un aviso en tu panel; `null` lo quita y el panel lo marca en rojo) y 30 escrituras por minuto por IP. - **Topes y cuota:** `maxRowsPerOwner` (por defecto 500; `null` = sin tope), `writesPerMinute` (`row_rate_limited`). Cada fila escrita cuesta cuota como un mensaje; en cosas masivas (un mapa de calor) junta los puntos y guarda cada pocos segundos. - **En el cliente** es el mismo SDK de siempre: `neblla.db.save(fila, { table })`, `neblla.db.load({ table, where, orderBy, limit })`, `neblla.db.delete({ table, id })` donde `id` es el valor de la clave (un objeto si es compuesta) o el número de `auto`. `neblla.session.freeTables` dice, por tabla, `key` (`none`, `auto` o `list`), `guests` y `write`; los topes no salen al cliente. Una fila `auto` nueva vuelve con `pending: true` y sin `id` hasta que tu base la confirma. - **Si tu base no contesta**, el guardado espera en la cola de Neblla y se repite con el mismo `nb_req`: no se duplica. **Esquema: solo se añade.** En el panel, Funciones › Datos › Tablas, o con `neblla_update_app`, puedes crear una tabla y **añadir** columnas. Quitar una columna de la declaración **la retira**: Neblla deja de usarla, pero **no hace `DROP`**; la columna y sus datos siguen en tu base, y puedes volver a declararla con el mismo tipo. Una tabla quitada se guarda en `retiredTables` y solo se reactiva con la misma clave. Lo que Neblla **no** hace, y es tuyo: cambiar el tipo de una columna (`column_type_locked`), cambiar la clave (`key_locked`), renombrar, borrar columnas o tablas, crear índices propios, copiar las tablas libres al migrar de base (empiezan vacías en la nueva; las filas siguen en la vieja) ni sus copias de seguridad. Si tocas la tabla a mano, **«Comprobar con mi base»** (o `POST /api/backend/apps//tables//check`) compara la real con la declaración sin tocarla, y Neblla se niega a escribir con otro tipo (`schema_mismatch`) en vez de guardar mal. Sin permiso para `CREATE`/`ALTER` en tu base, `byodb_permission` trae la sentencia exacta para que la ejecutes tú. Archivar o borrar la app **no** toca sus tablas: son tuyas. Scripts de ejemplo para lo que hace el developer (sustituye `_` por el nombre que te da «Usar con n8n»; haz copia antes): ```sql -- Postgres: cambiar el tipo de una columna (después, vuelve a declararla con el tipo nuevo) ALTER TABLE "_puntuaciones" ALTER COLUMN "puntos" TYPE BIGINT USING "puntos"::BIGINT; -- MySQL ALTER TABLE `_puntuaciones` MODIFY `puntos` BIGINT; -- SQLite / Turso: no hay ALTER TYPE; añade una columna nueva, copia, declara la nueva y retira la vieja ALTER TABLE "_puntuaciones" ADD COLUMN "puntos2" REAL; UPDATE "_puntuaciones" SET "puntos2" = "puntos"; -- Borrar una columna que ya retiraste (Postgres, MySQL y SQLite 3.35+) ALTER TABLE "_puntuaciones" DROP COLUMN "antigua"; -- Renombrar una columna (retira la vieja y declara la nueva con el mismo tipo; el script copia los datos) ALTER TABLE "_puntuaciones" ADD COLUMN "nivel" VARCHAR(255); UPDATE "_puntuaciones" SET "nivel" = "modo"; -- Un índice propio para tus consultas (Neblla ya tiene uno en nb_owner) CREATE INDEX "_puntuaciones_puntos" ON "_puntuaciones" ("puntos"); ``` **Agregados con n8n (o Metabase, o tu SQL).** Neblla no calcula agregados, rankings semanales ni mapas de calor sobre tablas libres: los datos ya están en tu base, y n8n, Metabase o un `cron` tuyo los leen directo, sin gastar cuota de Neblla. «Usar con n8n» (en la tabla del panel, o `POST /api/backend/apps//tables//n8n`) te da el nombre SQL, las columnas, los datos de conexión **sin contraseña** y un `SELECT` listo: ```sql -- el ranking: la mejor puntuación de cada modo (n8n: nodo Postgres / MySQL / SQLite → «Execute Query») SELECT "modo", MAX("puntos") AS "mejor" FROM "_puntuaciones" GROUP BY "modo" ORDER BY "modo"; -- recuento de votos de hoy por tema SELECT "tema", COUNT(*) AS "votos" FROM "_votos" WHERE "nb_at" >= CURRENT_DATE GROUP BY "tema"; ``` Y lo contrario también: n8n escribe en una tabla `write: 'server'` (un resumen del día) y tu app la lee con `db.load` o en una pantalla. Cuando n8n escriba directamente en tu base, rellena `nb_owner` (vacío) y `nb_at` (la hora en UTC) si quieres que las pantallas la ordenen bien. **Vistas: pantallas a medida.** Una tabla libre se mira con una pantalla (`neblla_set_panel`, o Funciones › Pantallas a medida en el panel): sus columnas, `updatedAt` (`nb_at`), `owner`, `id` (con `auto`) y `player.name`; filtro fijo, filtros del equipo, orden, `offset`; botones de fila solo si la tabla tiene clave. En «Quién la ve» eliges qué grupos del equipo la ven en el Back Office (`apps.teamGroups[id].panels`, solo el dueño); quien no está, no la ve. ## Sorteos justos: sobres de cartas, cofres, premios (`neblla.db.draw`) Un sobre de cromos, un cofre, una ruleta de premios: el usuario paga (créditos, o una apertura gratis cada tanto) y recibe cartas al azar. Lo justo lo pone Neblla: las reglas están en la configuración de tu app, no en el código del cliente, y cada apertura baraja el mazo entero de nuevo y escribe las cartas en la colección del usuario **antes** de enseñarlas. ```javascript neblla_update_app({ tables: { coleccion: { fields: { criatura: 'string', rareza: 'string', fuerza: 'integer' }, write: 'neblla' } }, draws: { sobre: { into: 'coleccion', // una tabla que solo escribe Neblla cards: [ { copies: 60, data: { criatura: 'brote', rareza: 'comun', fuerza: 1 } }, { copies: 1, data: { criatura: 'dragon', rareza: 'legendaria', fuerza: 9 } } ], perOpen: 3, // cartas por apertura (sin repetir copia) cost: [ { credits: 'gemas', n: 5 } ], // uno o varios precios, en tipos de crédito free: { everyHours: 24, max: 2 }, // una gratis al día, se acumulan hasta 2 } }, }) // client.js const { cards, paid, free } = await neblla.db.draw('sobre'); // gratis si hay, si no el primer precio que cubre su saldo await neblla.db.draw('sobre', { pay: 'gemas' }); // o elige: 'free' o un tipo de crédito const { cards: todas, cost, free: gratis, last } = await neblla.db.drawInfo('sobre'); // cada carta con su chance ``` - **La probabilidad es pública:** `drawInfo` da cada carta con `copies` y `chance` (copias / total), el precio, las aperturas gratis (`available`, `nextAt`) y la última apertura del usuario. Enséñala: es lo que piden las tiendas de apps para las cajas de botín. - **Pagar y recibir van juntos:** si no puede pagar, no se saca nada (`not_enough_credits` con `cost` y `nextFreeAt`; `no_free_open` con `nextAt`; `invalid_pay`). Si no le caben (`maxRowsPerPlayer`), `too_many_rows` antes de cobrar. Una apertura cobrada que se cortó a medias se termina sola (en la siguiente llamada del usuario o en un barrido del servidor). - **Un doble clic es una sola apertura:** `draw()` junta en una promesa las llamadas iguales (mismo sorteo y pago) mientras una va en camino, y si se corta la red tras enviar, el SDK repite UNA vez con el mismo identificador: el servidor devuelve esa misma apertura (`replayed: true`) y no cobra otra. Sin red al pulsar, `draw()` falla con `offline` y no cobra nada; con un corte a medias, con `not_connected` o `timeout`: vuelve a llamar con calma, `drawInfo().last` dice si llegó. - **Las cartas son filas normales** de la tabla, del usuario, con su `id`: las lee con `db.load`, se intercambian (Intercambios, abajo) y se llevan a una partida (servidor.txt, «Una baraja de cada jugador»). - **Reglas:** hasta 20 sorteos, 500 cartas distintas, 100.000 copias, 50 por apertura, 5 precios y 100 aperturas gratis acumuladas. Cada carta tiene que caber en los campos de `into`. Errores: `invalid_draws` (con `field`, `draw`, `reason`), `invalid_draw_name`, `draw_table_not_read_only`, `unknown_draw`. Se publican con el resto de la configuración (pre → pro). - **Tú lo revisas:** el MCP (`neblla_draws`: `info` y `opens`, el registro de aperturas por usuario) y el panel, en Funciones › Datos › Sobres y sorteos. Cada apertura cuesta como un mensaje. ## Puntuaciones de un juego para uno (`neblla.scores`) Un juego para uno (un Wordle, un juego de reflejos, un test) no tiene sala ni árbitro: su único servidor es el dispositivo del usuario, que puede mandar «lo acerté en 1» sin jugar. `neblla.scores` pone a Neblla en medio: la partida empieza en Neblla, la puntuación se manda contra esa partida una sola vez, y Neblla la comprueba antes de que entre en el ranking. Lo que no pasa no entra. Declaras cada ranking una vez, con `neblla_update_app({ scores })` o en el panel (Funciones › Puntuaciones y clasificaciones: crear, renombrar y borrar rankings, quién gana y sus límites), y "Pasar a pro". Renombrar un ranking se lleva sus puntuaciones al nombre nuevo, y borrarlo las borra (el panel lo avisa antes): las del borrador al momento, las de la app publicada cuando "Pasar a pro" lleva ese cambio (si el borrador usa los datos de la publicada, todas al pasar a pro); tirar los cambios del borrador (`neblla_promote` `reset`) devuelve sus puntuaciones renombradas a su nombre. En el MCP el renombre se dice: `neblla_update_app({ scores: { palabra: { … } }, scoreRenames: { wordle: 'palabra' } })`; sin `scoreRenames`, un nombre nuevo es un ranking vacío y el que falta se borra con sus puntuaciones. Si luego vuelves a una versión de antes del cambio de nombre («Volver a esta», `neblla_promote` con `action: 'rollback'`), las puntuaciones vuelven al nombre de esa versión, y el siguiente «Pasar a pro» las lleva otra vez al nombre nuevo. ```javascript // neblla_update_app({ scores: { // wordle: { order: 'asc', min: 2, max: 6, integer: true, minSeconds: 10, seed: 'daily', runsPerDay: 1 }, // reflejos: { order: 'asc', min: 120 }, // milisegundos: por debajo de 120 no lo hace nadie // puntos: { maxPerSecond: 50, check: { secret: 'MI_API', path: '/puntuacion' } }, // } }) const partida = await neblla.scores.start('wordle'); // → { run, seed, startedAt, until } // … el juego sale de partida.seed (con 'daily', la misma para todos hoy: la palabra del día) const r = await neblla.scores.submit(partida, intentos, { data: { palabras } }); if (r.ok) mostrar(r.best, r.place); // { ok: true, value, best, newBest, place } else avisar(r.reason); // { ok: false, reason: 'below_min' | … } const top = await neblla.scores.top('wordle', { period: 'day', limit: 10 }); // [{ place, player, value, at, info?, me? }] const mios = await neblla.scores.top('wordle', { period: 'day', friends: true }); // tú y tus amigos, con el puesto entre vosotros const yo = await neblla.scores.mine('wordle'); // { best, bestAt, dayBest, runs, place } o null ``` - **Los límites**, todos opcionales: `order` (`'desc'` por defecto, más es mejor; `'asc'`, menos es mejor: intentos, milisegundos), `min` y `max` del valor, `integer`, `minSeconds` (lo menos que dura una partida de verdad), `maxSeconds` (hasta cuándo se puede mandar una partida; un día por defecto, siete como mucho), `maxPerSecond` (puntos por segundo de partida), `seed` (`'run'`, una por partida; `'daily'`, la misma para todos los usuarios todo el día, que nadie puede saber antes), `runsPerDay` (partidas por usuario, ranking y día) y `timeZone` (zona IANA, p. ej. `'Europe/Madrid'`: en ella cambia el «día» del ranking, de `period: 'day'`, de `runsPerDay` y de la semilla diaria; **si no la declaras, el día es UTC**, como hasta ahora, y los rankings ya publicados no cambian). Hasta 20 rankings por app. - **La partida es de Neblla:** su hora la pone Neblla, así que el tiempo de juego no se falsea desde el cliente. Se manda una vez: el mismo valor otra vez (una respuesta que se perdió) recibe la misma respuesta; otro valor, `run_used`. Empezar otra cierra la que estaba abierta (`run_closed`), para que nadie abra varias y mande la de más suerte. - **Tu propia comprobación** (`check`): Neblla no ejecuta tu código, pero llama al tuyo. Con un secreto de `callApi` (`neblla_set_api_secret`), Neblla hace un POST a su dirección + `path` con `{ event: 'score', appId, board, player, value, data, run: { id, startedAt, seconds, seed, day } }`, y tu código (tu servidor, un Worker, una función en la nube) contesta `{ ok: true }` o `{ ok: false, reason }`. Ahí puedes rehacer la partida con `data` y la `seed`: que la palabra exista, que cada intento cuadre con el anterior. Antes de llamarte, Neblla ya rechazó lo imposible según los límites. Si tu código no contesta, `{ ok: false, reason: 'check_unavailable', retry: true }`: la partida sigue abierta y el mismo envío se puede repetir. `data`, hasta 16 KB. - **Lo rechazado no entra** y queda en el registro de tu app (Construir › Errores y rechazos, «Rechazado»; `neblla_get_logs` con `area: 'score'`). Lo que solo explica una trampa (`below_min`, `over_max`, `too_soon`, `too_fast`, `check_refused`) además marca al usuario, como una sala marcada: suben sus marcas (Personas › Moderación) y tu webhook `flag` recibe `{ room: null, board, reason, users }`. Los demás motivos no marcan: `invalid_value`, `run_expired`, `run_used`, `run_closed`, `run_not_found`, `check_unavailable`. - **Quién:** jugar para el ranking necesita login; el top lo lee cualquiera, también un invitado. Cada partida, envío y lectura cuenta como un mensaje de cuota (`db`). Errores de la llamada (la promesa se rechaza con `code`): `login_required`, `unknown_board`, `runs_per_day` (con `max`), `data_too_large`, `invalid_period`. - **El ranking** es una fila por usuario y ranking con su mejor marca de siempre y la del día (UTC, o la zona `timeZone` del ranking), y su `publicInfo` de ese momento (`info`). Vive en la base de datos de tu app (con BYODB, en tu base de datos: tabla `nb_scores`), se borra con el usuario y solo lo escribe Neblla. Tú lo lees, y quitas una puntuación, con `neblla_scores` en el MCP o en el panel (Funciones › Puntuaciones y clasificaciones, «Mejores puntuaciones»: las mejores de siempre o de hoy, de la publicada o del borrador, y «Quitar»; quien solo mira las ve y no quita ninguna). - **Un nivel entre jugadores (ELO).** `neblla_update_app({ scores: { nivel: { type: 'elo', start: 1200, k: 32 } } })` (también en Funciones › Puntuaciones, «Un nivel entre jugadores») es un ranking que no se juega con `start`/`submit` (`elo_board`): lo mueven los resultados de las partidas de un servicio con `results.board: 'nivel'` (ver core.txt, «Resultados de partidas»). Cada resultado que cuenta sube a los ganadores y baja a los perdedores según el nivel del otro lado (en parejas, la media): a 1200 contra 1200 con `k: 32`, ±16; ganar a alguien más fuerte sube más. `neblla.scores.top('nivel')` trae `played` y `won` en cada fila; `neblla.scores.mine('nivel')` → `{ rating, played, won, drawn, lost, place, history: [{ match, at, result, delta, rating }] }` (las 20 últimas, la más nueva primero); `neblla.scores.of('nivel', userId)` → `{ rating, played, won, place? }`, el nivel de otro (para ver con quién juega). Un resultado decidido tarde por el dev cuenta cuando se decide; uno anulado se quita y el ranking se vuelve a contar partida a partida. `neblla_scores` `setRating` `{ board, player, rating }` fija desde dónde empieza alguien (el nivel que trae de otro club), y sus partidas se recalculan desde ahí; en el panel, «Fijar el nivel» en sus mejores puntuaciones. - **Entre amigos:** `top(ranking, { friends: true })` es el mismo top solo con el usuario y sus amigos de Neblla que juegan a tu app y le dieron el permiso de amigos (la regla de `visible`, abajo); `place` es entre ellos. Pide login y el permiso de amigos del propio usuario (`login_required`, `scope_missing`). - **El torneo diario** (`neblla_set_automation` con `template: 'game.dailyTournament'`) lee este ranking con `board: 'wordle'`: cada día guarda el top del día en `nb_tournaments` y lo manda a tu secreto de API o a una sala como `{ event, board, day, ranking: [{ place, player, value, at, info? }] }`. `day: 'yesterday'` para uno que corre pasada la medianoche UTC. - En una sala el árbitro es otro: `neblla.tools.score` y los testigos (ver servidor.txt). ## Privacidad: publicInfo vs db.data `db.setPublicInfo()` se difunde a todos los miembros de la sala; `neblla.db.data` no llega a otros clientes (ni al peer que ejecuta `room.js`), salvo la parte que marques visible (abajo, «Lo que ven otros usuarios»). ```javascript // ❌ Mal — difunde datos sensibles a toda la sala: neblla.db.setPublicInfo({ name, email: neblla.db.data.email }); // ✅ Bien — solo lo que de verdad es público: neblla.db.setPublicInfo({ name, avatar }); // El email se queda en neblla.db.data, no llega a otros clientes ``` ## Lo que ven otros usuarios Lo que guarda cada usuario es suyo: nadie más lo lee. Si tu app necesita enseñar algo de uno a otros (la colección de una amiga, el perfil de recetas de alguien, las puntuaciones de un amigo), **marcas qué parte y para quién**, y el resto sigue sin salir nunca: ```javascript neblla_update_app({ visible: { data: { cartas: 'friends', faltan: 'friends', 'perfil.nombre': 'all' }, // rutas de db.data tables: { recetas: 'all', cartas: 'friends' }, // las filas de una tabla } }) ``` - **`'all'`**: cualquier usuario de tu app, también un invitado. **`'friends'`**: sus amigos en Neblla (una amistad aceptada), si él dio a tu app el permiso de amigos (`scopes: ['friends']` al hacer login), y él mismo. Si no lo dio, sus amigos lo leen como cualquier otro: un dato `'friends'` no sale y una tabla `'friends'` responde `not_friends`. Lo que no marcas no lo ve nadie, ni sus amigos. - **Rutas de `db.data`**: una clave de arriba (`cartas`) o con puntos (`perfil.nombre`, hasta 5 niveles), 50 como mucho; de una tabla se ven todas sus filas, sin el dueño. Es configuración: va al borrador y llega a los usuarios al publicar. También en el panel, Funciones › Datos y tu base de datos › «Lo que ven otros usuarios». ```javascript // El perfil de una amiga: sus 40 cartas y las 12 que le faltan const amiga = neblla.social.friends[0]; const suyo = await neblla.db.dataOf(amiga); // { cartas: {...}, faltan: [...], perfil: { nombre } } const filas = await neblla.db.loadOf(amiga, { table: 'cartas', orderBy: '-nivel', limit: 50 }); ``` - **`user`** es cualquier id que tu app tenga de esa persona: su id en la app (`appUserId`, el `author.id` de la comunidad), su id en la sala (`neblla.room.users`) o el `id` de un amigo de `neblla.social.friends`; o el objeto mismo. El de un invitado da `user_not_found`: no guarda nada. - **`dataOf`** devuelve solo las rutas que le tocan a quien lee (`{}` si ninguna); **`loadOf`** acepta lo mismo que `db.load` (`where`, `orderBy`, `limit`, `offset`) y responde `not_friends` si la tabla es solo para amigos y no lo es, `not_visible` si la tabla no está marcada. Una app que no marca nada responde `not_visible`. - Se lee donde vive, como el resto: la base de datos de Neblla o tu base de datos (BYODB), y el pre con los datos de pro lee los de pro. Lo que ese usuario guardó y aún espera en su navegador no se ve hasta que sale. Cada lectura cuesta como un mensaje. ## Intercambios entre usuarios Un usuario ofrece algo suyo a otro a cambio de algo de ese otro (una carta por otra, tres gemas por una espada, un regalo sin nada a cambio). **Solo pasa si el otro acepta, y de una vez**: se mueve todo o no se mueve nada, también si algo cambió entre la oferta y la aceptación. Declaras qué se puede intercambiar: ```javascript neblla_update_app({ trade: { tables: ['cartas'], // sus filas cambian de dueño products: ['gemas', 'espada'], // unidades de lo comprado (de un solo pago o consumibles; una suscripción nunca) with: 'friends', // 'friends' (por defecto: solo entre amigos de Neblla) o 'all' days: 3, // lo que dura una oferta si no dice otra cosa (1–30, 3 por defecto) } }) ``` ```javascript // Ana ofrece a Luis su carta del dragón y 3 gemas por la carta del troll de él const oferta = await neblla.db.offer({ to: luis, // cualquier id suyo, como en db.dataOf give: [{ table: 'cartas', id: 'r_dragon' }, { product: 'gemas', amount: 3 }], get: [{ table: 'cartas', id: 'r_troll' }], expires: Date.now() + 86400000, // opcional: hasta 30 días }); // Luis la oye y la ve neblla.db.on('offer', ({ action, offer }) => { /* action: new | done | declined | cancelled | failed */ }); const pendientes = await neblla.db.offers(); // las suyas, pendientes; { status: 'done' } es su registro await neblla.db.acceptOffer(oferta.id); // o declineOffer(id); Ana puede cancelOffer(id) ``` - **Lo que se intercambia**: filas propias de una tabla de `trade.tables` (`{ table, id }`; las de un grupo no) y unidades de un producto de `trade.products` (`{ product, amount }`). Lo que cada usuario guarda con `db.save()` (su documento) **no** se intercambia: lo escriben sus dispositivos, y uno que aún no supiera del cambio volvería a escribir lo de antes. Si algo de ahí tiene que pasar de mano, haz que sea una fila. - **La oferta** comprueba lo que da quien ofrece (que sus filas son suyas, que tiene las unidades) y guarda cómo estaban sus filas: quien la recibe las ve en `give[].row` (sin dueño). Lo que pide no se comprueba ni se enseña hasta que se acepta. - **Aceptar** lo hace todo de una vez: si alguna fila de quien ofreció cambió o ya no es suya (`offer_changed`), si a alguno no le quedan unidades (`insufficient_amount`), si no cabe (`too_many_rows`, el `maxRowsPerPlayer` de la tabla), si ya tiene un producto de un solo pago (`already_owned`) o si tu app dejó de permitirlo (`not_tradable`), no se mueve nada, lo ya movido vuelve y la oferta queda `failed` con su `reason`. Responde con la oferta `done`, y los dos la oyen. - Una oferta solo se responde una vez: aceptada, rechazada, cancelada o caducada, otra respuesta da `offer_closed` (con su `status`) u `offer_expired`. Quien la recibe acepta o rechaza; quien la hizo cancela. Cada usuario tiene como mucho 50 ofertas pendientes (`too_many_offers`). - **Las compras**: el pago se queda con quien pagó. Quien da pierde las unidades (o el producto de un solo pago); quien recibe tiene las suyas, que no son una venta (no salen en Dinero › Ventas ni se reembolsan). Los dos oyen `neblla.shop.on('purchase')` con lo que tienen ahora (`type: 'trade'`). Un producto de dinero real solo se intercambia si lo pones en `trade.products`. - **El registro**: cada intercambio queda un año, con quién, qué, cuándo y cómo acabó. Tú lo ves en el panel (Funciones › Datos › «Intercambios entre usuarios») y con `neblla_trades_read({ appId, action: 'list' })`, donde también cancelas una oferta pendiente. Es configuración: va al borrador y llega a los usuarios al publicar. Cada llamada cuesta como un mensaje. - Errores: `trade_off` (tu app no declara nada), `not_friends`, `self`, `not_owned`, `not_tradable`, `invalid_offer`, `invalid_amount`, `invalid_expires`, `user_not_found`, `offer_not_found`, `login_required` (un invitado no intercambia). ## Copias de seguridad de los datos de tu app Neblla hace cada día una copia cifrada de sus bases de datos, y de ella salen las copias de tu app: las de los **últimos 7 días** (**30 con Pro**), en el panel (Funciones › Datos › Copias de seguridad) y con `neblla_backups_read({ appId, action: 'list' })`. Cada día dice cuántas filas guarda de la publicada y del borrador, por tipo: usuarios, guardados, tablas, buzón, comunidad, chat de las salas, salas y compras. Si Neblla aún no guarda copias, `enabled: false`. **«Restaurar» pone una copia entera en su sitio**, la de la publicada o la del borrador por separado (`neblla_backups({ appId, action: 'restore', date: 'AAAA-MM-DD', env: 'pre' })`; sin `env`, la publicada). Todo lo de ese entorno vuelve a como estaba ese día: los guardados, las tablas, el buzón, la comunidad, el chat y las salas; lo que se escribió después se pierde. Los usuarios que siguen en tu app recuperan su ficha de ese día, pero siguen siendo quienes son (su cuenta de Neblla no cambia). Quien llegó después conserva su ficha, sin datos (la copia no los tiene). Quien fue borrado después (lo pidió él o lo borraste tú) **no vuelve**, ni sus datos: el RGPD manda. Las compras y los clientes de Stripe nunca se cambian ni se borran, porque son cobros de verdad: solo vuelven las de la copia que falten. No se deshace; confírmalo antes. Restaurar usa el mismo bloqueo corto que una migración de BBDD: los usuarios oyen `neblla.app.on('maintenance')` y vuelven a entrar solos en unos segundos. Gasta de la cuota de tu app como una migración (las filas leídas de la copia y escritas, y sus bytes, tipo `migration`); con la cuota del día agotada no empieza (`quota_exceeded`, con `resumesAt`), y una vez empezado termina. Va en segundo plano: `neblla_backups_read({ appId, action: 'status' })` dice si sigue (`running`), si terminó (`done`, con lo que puso por tipo, `erasedSince` y lo gastado en `cost`) o si falló (`failed`, `interrupted` si Neblla se reinició a medias: vuelve a restaurar, empieza de cero). No se puede restaurar mientras la app migra de BBDD (`migrating`) ni dos veces a la vez (`already_restoring`). **Con tu propia BBDD (BYODB), las copias son cosa tuya**: los datos están en tu base, Neblla no los copia y el panel te lo dice (`byodb: true`, sin filas). Haz copias con las herramientas de tu proveedor. ## BBDD propia del desarrollador (BYODB) Los datos sincronizados consumen cuota. Un `db.save()` se cobra por lo que mandas, a la mitad de tarifa que el resto de bytes de payload (con `mode: 'full'`, el documento entero, porque es lo que mandas). Así que guarda poco y cuando cambie algo con sentido, no en cada frame, y recuerda que con BBDD propia configurada (abajo) deja de contar el **almacenamiento**, no la escritura: el payload sigue costando sus bytes porque sigue cruzando el servidor. Para más almacenamiento — o para que los datos vivan en BBDD propia — se aportan credenciales desde el dashboard, o se conecta la base una sola vez en la cuenta o en un proyecto (`neblla_projects` con `connect_db`) y la usan todas sus apps (Explorer usa la de la cuenta; un proyecto puede poner la suya y heredar el resto). Con una base compartida por varias apps, las tablas de cada app llevan su propio prefijo. Engines soportados: ``` Engine Proveedores compatibles (ejemplos) Tier free típico ───────── ───────────────────────────────────────── ──────────────── MongoDB Atlas, DocumentDB, Cosmos DB (Mongo API) Atlas M0 = 512 MB Postgres Neon, Supabase, RDS, Aurora, Render Neon = 3 GB MySQL PlanetScale, RDS, Cloud SQL, Aurora varía Turso Turso.tech (libSQL distribuido) 9 GB ``` **Qué va a tu BBDD**: los blobs JSON que la app genera — `db.save()` (user.data), datos de salas (`room.setData`) y comunicaciones dev↔user. Tres "tablas"/colecciones para datos de usuario (`user_data`, `room_data`, `user_communications`) — y si la app usa Comunidad, esa feature guarda además sus propias tablas en la misma BBDD (**una sola copia, no un espejo**: la base de datos de comunidad es o tu BBDD o la de Neblla, nunca las dos, y sin BBDD propia el sitio por defecto es una Turso de Neblla, no su Mongo) (`community_entries`, `community_entry_tags`, `community_relations`, `community_links`, `community_payloads`, ver comunidad.txt), así que dimensiona también para ellas creadas automáticamente con sus índices la primera vez que Neblla escribe. Esquema estable y documentado. **El chat de tus salas también va a tu BBDD**, en la tabla `neblla_nb_room_messages` (`room`, `sender`, `deleted`, `at` como columnas; el mensaje en el JSON): en claro, para que lo leas con tus consultas, con el id del usuario en tu app y nunca su id de Neblla. Neblla no guarda copia; el tope de mensajes por sala y el límite por minuto se aplican igual. Si tu BBDD no responde, la línea espera en Neblla y se escribe en cuanto vuelve. **También van a tu BBDD tus usuarios**: el registro de los usuarios de tu app (`neblla_app_users`: su id en tu app, su nombre público, email, idioma, cuándo entraron y la última vez, sus baneos, flags y marcas de la comunidad), las compras hechas en tu app y una copia de las amistades entre usuarios de tu app. La ficha de cada usuario en tu app solo está ahí: Neblla guarda un puntero (el id en tu app y de qué cuenta de Neblla es) y lee y escribe la ficha en tu BBDD. Si borras a mano la fila de un usuario, la próxima vez que entre se le hace una ficha nueva y limpia: sin sus baneos, flags ni marcas, porque solo estaban en esa fila; si quieres que siga expulsado, no borres su fila. Si tu BBDD no contesta, entrar en tu app se para con el error `store_unavailable` hasta que vuelve (por cualquier camino de entrada: te llega en `neblla.auth.on('error')` y en `neblla.app.on('error')`, y la ventana de login se lo dice al usuario); quien ya está jugando sigue, y una flag puesta mientras tanto espera en Neblla y se escribe al volver. Las compras hechas en tu app y los clientes de Stripe de tus jugadores (`neblla_app_purchases`, con el id del jugador en tu app en `user_id`, y `neblla_app_customers`) también son solo tuyos: lo que queda de cada compra, sus reembolsos, disputas y suscripciones se leen y se escriben en tu BBDD, y Neblla no guarda copia; las compras de prueba de la pre van con `test = 1`. Si borras a un jugador que tenía compras, sus compras se quedan en tu BBDD y Neblla guarda solo de qué cuenta de Neblla eran, para que las recupere si vuelve. Si tu BBDD no contesta, no se puede comprar ni gastar (`store_unavailable`), y lo que avisa Stripe (pagos, reembolsos, renovaciones) espera en Neblla y se aplica en orden cuando vuelve; lo que lleve 30 días esperando se descarta y habría que aplicarlo a mano desde el panel de Stripe. Si tu app ya tenía BBDD propia antes de este cambio (octubre de 2026), sus fichas, compras y registros siguen en Neblla hasta que Neblla los traslade o hasta tu próxima migración de BBDD. **Los registros de lo que pasa en tu app también son solo tuyos**, en tu BBDD: los casos del anti-trampas (`neblla_nb_fog_cases`, con los estados comparados), los avisos de compras que el dispositivo dijo tener sin pagarlas (`neblla_nb_fraud_reports`, bajo el jugador) y los avisos legales sobre tu comunidad (`neblla_nb_legal_notices`: el caso entero y la dirección postal de quien avisa, sin su nombre, email, organización ni firma). Un caso del anti-trampas se borra solo a los 30 días de abrirse, salvo que actives «Guardar los casos hasta que yo los borre» en el panel (Personas › Moderación) (o `keepFogCases: true` en `neblla_update_app`): entonces se queda hasta que lo borres tú. Neblla guarda solo lo suyo: una copia del caso que anulas mientras lo revisa (la borra al cerrar la revisión) y una copia mínima de cada aviso legal (el aviso, quién lo presentó y lo que se hizo, sin la dirección), que se borra sola a los 3 años de cerrarse el caso. Si tu BBDD no contesta, el backoffice no puede listarlos (`store_unavailable`) y lo que se escribe espera en Neblla. **Las estadísticas de tus jugadores, si las quieres.** Apagadas por defecto: se encienden en la pestaña Estadísticas del panel (o con `playerStats: true` en `neblla_update_app`), que antes de encenderlas te dice cuánto costarán con las visitas de ahora, en euros y en % de la cuota del día (`cost`). Encendidas, Neblla guarda en tu app (con BYODB, en tu BBDD) dos tablas: `neblla_nb_player_stats`, una fila por jugador (id = el del jugador en tu app) con su primera y su última visita, cuántas y de dónde vino la primera (`src`, `cmp`); y `neblla_nb_stats_days`, una fila por día y por semana (UTC) solo con contadores, así que leer 30 días no recorre a tus jugadores. Con eso la pestaña (y `neblla_get_stats`, o `POST /api/backend/apps//stats` con la sesión del panel) enseña los últimos 30 días: activos por día y por semana con la tendencia, nuevos, de dónde vienen (el `utm_source` de la dirección de su primera visita, si no la web de la que llegaron, si no «direct»; «neblla» es la galería; y las campañas, `utm_campaign`), si vuelven (al día siguiente, a los 7 y a los 30 días), el tiempo medio de uso (con la app abierta y a la vista), el dinero por semana y por producto (de las compras y de cada periodo pagado de una suscripción, menos los reembolsos, que restan el día en que se reembolsan) y, si tu app tiene reservas, la ocupación de cada clase y horario; y «Descargar CSV» (`format: 'csv'`), una fila por día. Cuentan los jugadores que hacen login. El SDK no manda ningún mensaje más: de dónde vino la primera visita va con su conexión, y el tiempo lo mide el servidor. Los días son UTC, como la cuota. Cada visita es una escritura en tus tablas (los contadores del día se suman en memoria y se escriben como mucho una vez por minuto), todo gasta de la cuota de tu app como cualquier escritura en tus tablas, también leer la pestaña, y con la cuota del día agotada no se apunta. Son tuyas: Neblla mide aparte lo suyo (las "Apps jugadas" de la cuenta de cada persona) y nunca lee estas tablas; solo para decirte cuánto costarían antes de encenderlas mira cuántos jugadores vinieron estos días. **El email de un usuario registrado va a tu BBDD.** Un invitado solo deja su id. **Cada usuario tiene un id distinto en cada app.** Tu BBDD solo ve el de tu app, así que si se filtrara no se puede cruzar con los usuarios ni las amistades de otras apps. **Qué se queda en Neblla**: lo operativo. La cuenta Neblla de cada persona (con qué hace login, sus sesiones y tokens, que son los mismos en todas las apps), el puntero de cada jugador (su id en tu app y de qué cuenta es) con las reseñas y favoritos de la galería, su propia medición de visitas, la copia de los casos que revisa y la copia mínima de los avisos legales, la configuración de tu app, los ficheros alojados, la cuota y los logs. Migración transparente por fases (copia masiva → delta de cambios → swap final). Se lleva todo lo que la app guarda: guardados, salas y su chat, comunicaciones, la comunidad (entradas con su contenido, valoraciones, favoritos y enlaces), las filas de tus tablas y las de grupos, enlaces compartidos, reservas y créditos; y en el último paso pasan a tu BBDD como originales las fichas de tus usuarios, sus compras y clientes de Stripe, los casos del anti-trampas, los avisos de fraude y los avisos legales (Neblla se queda solo con lo suyo, arriba). El último paso bloquea la app unos segundos para asegurar zero data loss. La app se entera con `neblla.app.on('maintenance')` (`{ reason: 'byodb_migration', retryInSeconds: 30 }`): el socket se desconecta en ~2 segundos y el SDK vuelve a conectar solo pasados `retryInSeconds` (mínimo 5 s); si la app sigue bloqueada, oye otro aviso y lo vuelve a intentar más tarde — muestra un mensaje de mantenimiento mientras tanto. Tras la migración, `db.save()` y los demás blobs van directos a tu BBDD: lo que dejas de gastar es el almacenamiento, no la operación — la escritura sigue cruzando Neblla y sigue costando sus bytes de payload. **Volver a la BBDD de Neblla es otra migración.** Quitar tu BBDD (el botón «Volver a la base de datos de Neblla» del panel, `neblla_byodb({ action: 'to_neblla' })`) no deja la app vacía: es la misma migración por fases al revés, que copia de tu BBDD a donde vive cada cosa sin BBDD propia (las Turso y la Mongo de Neblla) los guardados, las salas y su chat, las comunicaciones, la comunidad, las filas de tus tablas, las fichas de tus usuarios, sus compras y clientes de Stripe, los casos del anti-trampas, los avisos de fraude y los avisos legales, y entrega también lo que esperaba en Neblla para escribirse en tu BBDD. Termina con el mismo bloqueo corto. Lo que queda en tu BBDD no se borra: es tuyo. Si tu BBDD ya no contesta, no se puede copiar nada de ella: la llamada falla con `store_unavailable` y `canStartFresh: true`, y el panel te ofrece «Empezar de cero en la base de datos de Neblla» (`neblla_byodb({ action: 'to_neblla', fresh: true })`): la app sigue con sus jugadores (cada uno con su mismo id en tu app), pero sin sus guardados, fichas, compras ni registros, y lo que esperaba para tu BBDD se descarta. Solo se ofrece mientras tu BBDD no contesta; si vuelve a contestar, migra. **Si tu BBDD no contesta.** Lo que tus usuarios guardan espera en una cola de reintento de Neblla (y su copia en Neblla), cuanto haga falta: una base que no contesta (caída, red, mantenimiento largo, un Supabase en pausa) no gasta intentos ni aparta nada, por muchas horas que dure. Solo una base que contesta y rechaza la escritura una y otra vez la aparta; `neblla_byodb({ action: 'status' })` dice cuántas esperan y cuántas se apartaron (`queue`), y `neblla_byodb({ action: 'retry_queue' })` las devuelve a la cola. Mientras no contesta, tus usuarios oyen `store_unavailable` al entrar, y tú recibes el aviso «Tu base de datos no responde» en cuanto el primero lo nota. Borrar a un usuario cuando tu base no contesta tampoco se da por hecho: el borrado espera en la cola y la petición queda `partial` hasta que la base lo recibe. **Si cambias la clave de tu BBDD.** Si rotas el usuario, la contraseña o el token de la base que ya usas (misma base, mismo host y mismo nombre), no migres: `neblla_byodb({ action: 'update_credentials', engine, config })` (o «Cambiar credenciales» en el panel) valida la clave nueva, la guarda cifrada y lo que esperaba en la cola sigue su camino, sin copiar nada; el aviso «tus credenciales ya no valen» se cierra solo. Si el destino es otro (otro host o otra base) responde `credentials_target_differs`: el camino es `migrate`. Solo el owner puede, y la respuesta nunca devuelve la clave. Mientras la clave no vale, tus usuarios oyen `store_unavailable` y lo que guardan espera, como con una caída. **Tus migraciones gastan de la cuota de tu app**, de ida y de vuelta: las lecturas, las escrituras y los bytes que mueven (tipo `migration` en el desglose de la cuota). Si la cuota del día se acaba, la copia se para y sigue sola donde se quedó tras el reinicio diario (00:00 UTC) o en cuanto añades créditos; el bloqueo final siempre termina, aunque pase de la cuota, y lo que gasta también se cobra. El panel y `neblla_byodb_read({ action: 'status' })` dicen cuánto lleva y cuánto le queda (`progress`), lo gastado (`cost`, en créditos) y si espera a la cuota (`pausedForQuota`, `resumesAt`). El traslado que hace Neblla de las fichas y registros de las apps que ya tenían BBDD propia no gasta tu cuota. **Neblla con tu Supabase.** Si ya usas Supabase (o Neon, RDS…), conéctalo con `neblla_byodb` como base Postgres: tus usuarios, sus compras, la comunidad y tus tablas viven ahí, con columnas que consultas con tu SQL. Neblla pone lo que Supabase no trae: cobros y suscripciones, comunidad con moderación, salas, el login (o el tuyo, con BYOAuth), el RGPD y el backoffice. Una sola base, sin puentes entre dos sistemas. ## Escribir a todos tus usuarios Un mensaje a todos los usuarios de tu app, o a los de un grupo (y, dentro, a un papel: «solo los profes de la clase A»), que llega al buzón de cada uno como cualquier mensaje tuyo: el SDK lo avisa como un mensaje nuevo (`neblla.inbox.on('updated')` con `action: 'created'` y `from: 'dev'`), en vivo si está conectado y al volver si no. En el panel es Personas › Usuarios › «Escribir a todos»; con Claude, `neblla_broadcast`. Necesita el módulo `inbox`. **Se paga por destinatario** con la cuota de tu app, como cualquier mensaje a un usuario: el fijo de salida de un mensaje más los bytes del texto y de `data` (tipo `newCommunication`, módulo `inbox` en el desglose). Antes de mandarlo, el servidor te dice cuánto costará: cuántos lo recibirán, cuánto cuesta cada uno y el total, cuánto te queda hoy y a cuántos llega con eso (`reachable`). ``` POST /api/backend/apps//broadcast/estimate { authToken, message, data?, group?, role? } → { recipients, perRecipient, credits, available, ceiling, percentOfDay, fits, reachable } POST /api/backend/apps//broadcast/send (lo mismo) → { broadcast, estimate } POST /api/backend/apps//broadcast/status { authToken, id } → { broadcast } ``` **Con muchos usuarios** el envío contesta al momento y sigue por tandas sin parar nada más (`status`: `sending`, `done`). Nunca se pasa de la cuota: antes de cada mensaje mira lo que queda del día, y si no llega para el siguiente para ahí (`stopped_quota`, con `resumesAt`, el reinicio de las 00:00 UTC) y te lo dice, también en los avisos de la app (`broadcast_paused`, en Personas › Usuarios); tras el reinicio de la cuota sigue sola donde se quedó, sin repetir a nadie, como una migración. Si compras cuota antes, `resume` (`/broadcast/resume`, o `neblla_broadcast` con `action: 'resume'`) sigue al momento. Un usuario terminado no lo recibe ni se cobra (`skipped.terminated`), ni uno con el buzón lleno (`skipped.inboxFull`). Una sola tanda a la vez por app (`broadcast_running`). El mensaje: texto de hasta 5.000 caracteres y `data` opcional, como en `neblla_send_communication`. Quien te escribe sin cuenta desde el formulario de contacto de tu web (social.txt, «Gente sin cuenta») no es un usuario: tiene su hilo en el Buzón y nada más, y «Escribir a todos» no le llega. ## Borrar los datos de un usuario (RGPD) **El marco legal ya está hecho.** Al crear tu primera app aceptas el contrato de encargo (DPA) en https://neblla.com/legal/dpa, y la lista de subencargados, con dónde está cada uno, está en https://neblla.com/legal/subprocessors. Las bases de datos de Neblla están en la UE (Fráncfort e Irlanda), y lo que sale de la UE va cubierto por las cláusulas tipo de la Comisión Europea. Con BYODB, los datos de tu app están donde tú elijas. Lo que un usuario da a tu app es tuyo, y su borrado también es responsabilidad tuya. Neblla te lo pone fácil: desde tu app, `neblla.auth.requestErasure()` abre una ventana de Neblla donde el usuario lo confirma con un clic; ningún script puede hacerlo por él (la ventana no se puede enmarcar y solo confirma con una cookie que pone la propia ventana). La petición te llega al backoffice y a tu bandeja, y un botón borra todo lo estándar de Neblla: sus datos guardados, mensajes, registro, reseña y favorita, también en tu BBDD. Lo mismo hace `neblla_erase_user` (también corta su conexión, en pro y en pre, y vacía lo que tuviera en cola), y `neblla_export_users` te da sus datos para entregárselos. Sus compras se conservan, pero **sus suscripciones se cancelan en Stripe al momento** (sin devolver nada: las devoluciones son tuyas, en Stripe; si Stripe falla, Neblla lo reintenta), y **su cliente en tu cuenta de Stripe no se borra**: es tuyo, con tus obligaciones fiscales; si lo necesitas, bórralo en Stripe (la respuesta de `neblla_erase_user` te lo recuerda). Si prefieres gestionarlo tú, desactiva la ventana en la configuración de la app. **Si alguien borra su cuenta Neblla, tu usuario se queda con todo lo suyo en tu app, incluido el email con el que se registró.** Ya no puede hacer login con su cuenta Neblla, pero si tu app tiene otra forma de hacer login, ese email te permite reconocerlo y que siga. --- Capítulo social de la guía Neblla — amigos y comunicaciones dev↔usuario. El contrato base está en core.txt; el criterio de cuándo usar Neblla, en empezar.txt. # Social ## Amigos Las amistades son entre personas (cross-app), pero todo lo que la app ve está filtrado por app: un amigo solo aparece si concedió el scope `discoverable` para *esta* app, y "online" significa "conectado a esta app ahora mismo". Requiere el scope `friends` en el login. ```javascript console.log(neblla.social.friends); // [{ id, name, picture, online, ... }, ...] ``` Métodos: ```javascript neblla.social.request(targetUserId); // mandar petición a otro usuario online en esta app neblla.social.accept(requestId); neblla.social.reject(requestId); neblla.social.remove(friendId); // funciona offline neblla.social.inviteFriend(targetUserId); // "ven a mi sala" (cualquier tipo de sala) neblla.social.inviteToRoom(targetUserId); // añade a la whitelist de tu sala privada await neblla.rooms.direct(amigo); // «Escribir»: la sala privada de los dos (receta en salas.txt) await neblla.db.dataOf(amigo); // lo suyo que tu app deja ver a sus amigos (identidad.txt, «Lo que ven otros usuarios») await neblla.db.offer({ to: amigo, give: [{ table: 'cartas', id }], get: [] }); // regalarle una carta: la acepta y es suya (identidad.txt, «Intercambios entre usuarios») await neblla.social.list(); // refresh manual de social.friends y social.requests; devuelve los amigos ``` Para añadir a alguien que **no** está en la app ahora mismo, usa su código de amistad (su handle público de Neblla): `neblla.social.request({ code })` le deja la petición en su buzón aunque esté desconectado, y la verá en `social.requests` la próxima vez que abra una app con el scope `friends` (`target_not_found` si el código no existe, `self` si es el tuyo). `await neblla.social.code()` devuelve el código del usuario para que lo comparta (`null` si aún no ha elegido handle en play.neblla.com). Y el enlace `https://play.neblla.com/u/` abre la pestaña de amigos de su cuenta Neblla con el código ya puesto: un clic para mandar la petición. Eventos: `neblla.social.on('request')` (`{ requestId, from }`), `on('accepted')`, `on('removed')`, `on('updated')` (`{ friends }`), y la invitación a una sala, `neblla.rooms.on('invite')` (`{ from, roomName, appId, type }`). Propiedades: `neblla.social.friends` (amigos visibles en esta app), `neblla.social.requests` (peticiones recibidas). ### La partida de un amigo y «Unirme» Un amigo conectado a esta app y metido en una sala trae su partida: `friend.room = { name, state, joinable, reason }`. `state` es `gathering` o `running`; `joinable` es lo que Neblla calcula **para quien mira**; si es `false`, `reason` dice por qué: `full` (la sala llegó a `matchmaking.maxPlayers`), `started` (la sala ya está en `running`), `private` (sala con lista de invitados en la que no estás: sale **sin nombre**, `name: null`) o `closed` (la cerró el desarrollador con `room.setJoinable(false)`, salas.txt). Si el amigo está en el lobby, en un chat de dos amigos, en una sala `private` o en ninguna, `room` es `null`: sale «en línea» y nada más. **Amigo ausente (OP-2).** Un amigo cuyo socket se perdió hace unos segundos (móvil bloqueado, pestaña cerrada; hasta un minuto si la red se cortó de golpe) sale con `away: true`, `online: false`, `userId: null` y `room: null`: Neblla le guarda el sitio, pero no ofrece «Unirme» a la sala de un fantasma. Cuando vuelve, la lista se actualiza sola (`friendsUpdated`). `social.inviteFriend(id)` responde `{ ok: true, away: true }` si el amigo estaba ausente: la app puede decir «te avisaremos cuando vuelva»; el aviso (`roomInvite`, y también `friendRequest`, `friendAccepted`, `friendRemoved`, `appInvite`) se le entrega al volver. El botón lo pone tu app (o no): Neblla no dibuja nada. ```javascript neblla.social.friends.forEach(f => { const r = f.room; if (!r || r.name === neblla.room.name) return; // sin partida, o ya estás en ella if (r.joinable) mostrarBoton('Unirme', () => neblla.rooms.join(r.name)); // el join sigue con sus barreras reales (joinError) else mostrarGris(r.reason); // full | started | private | closed }); ``` `joinable` es información, no una cerradura: `rooms.join` sigue aplicando `not_invited`, `not_whitelisted` y `room_full`. La lista se actualiza en vivo (`social.on('updated')`) cuando la sala se llena, empieza o el desarrollador la abre o cierra, también para los amigos de los demás jugadores de la sala. Una app sin `start()` (una sala de estudio, un chat en vivo) sale abierta mientras haya sitio; un juego que empieza sale `started`, salvo que admita entrar a mitad (`room.setJoinable(true)`). ## Invitar a un amigo de Neblla A LA APP Distinto de `social.inviteFriend` (que es "ven a mi sala" dentro de la app). Aquí el usuario trae a un amigo que aún no conoce la app: ```javascript await neblla.social.inviteToApp(); // requiere usuario logueado ``` - Abre un popup alojado por Neblla donde el usuario elige a un amigo de su lista — la app **nunca** ve esa lista, ni quién fue elegido. - Fire-and-forget: ni el invitador ni la app saben si el amigo estaba online o si le llegó. - No requiere el scope `friends`. - El amigo ve la invitación en su bandeja en play.neblla.com (caduca a las 24 horas) con un enlace que lo trae a la app con `?nbla_invite=`. Cuando alguien abre la app desde una invitación (o cuando un amigo lo invita estando ya dentro), el SDK rellena `neblla.social.invitedBy` (`{ id, name, picture, slug, userId|null }` — `userId` es el id por-app del que invitó si está online ahora) y dispara `neblla.social.on('appInvite')` (`{ from }`). Si el enlace caducó (24 h) o no es válido, llega `{ from: null, expired: true }`: la app puede decir «esta invitación ha caducado». Si el invitado luego hace login, su amigo aparece en `neblla.social.friends` (si concedió `discoverable`), y con `neblla.social.invitedBy.userId` se le puede meter a una sala al instante. ## Comunicaciones dev↔usuario Canal para que el usuario hable con el desarrollador sin salir de la app. Requiere login. Es el módulo `inbox`: `neblla_update_app` con `features: { inbox: true }` — ese es el interruptor que comprueba el servidor, y sin él `inbox.send` responde `feature_disabled`. El campo `inbox` de primer nivel NO es el interruptor: lleva el tope por usuario (`{ maxPerUser }`). Un buzón guarda como máximo **100 mensajes por usuario en gratis y 2000 en Pro**; el dev puede bajarlo pero no subirlo por encima del techo de su plan, y pasarse responde `communications_full`. ```javascript const { communication } = await neblla.inbox.send({ message: 'Encontré un typo en la pantalla de resultados', data: { type: 'bug' } }); ``` Firma completa: `neblla.inbox.send({ message, data?, dateFrom?, dateTo?, thread? })` **(CLIENT)**. El desarrollador lo ve en el backoffice de developers.neblla.com — con el id del usuario, la fecha, la categoría asignada en `data.type` — y puede responder desde allí. El evento `inbox.on('updated')` avisa en cliente de cualquier cambio en tiempo real: ```javascript neblla.inbox.on('updated', ({ communication, action }) => { if (action === 'created' && communication.from === 'dev') { showToast('Tienes respuesta del desarrollador'); } }); ``` Otros métodos: - `neblla.inbox.update(commId, {...})` **(CLIENT)** — edita una comunicación propia (mientras no esté marcada como leída). - `neblla.inbox.delete(id)` **(CLIENT)** — borra la suya. Eventos: `neblla.inbox.on('messages')` **(CLIENT)** — la lista entera (sync inicial y cada vuelta); `neblla.inbox.on('updated')` **(CLIENT)** — `{ communication, action }`, cada cambio, también los de cuando no estabas (al volver llega uno por mensaje nuevo o borrado). Propiedad: `neblla.inbox.messages` **(CLIENT)** — array de comunicaciones del usuario. Para escribir a todos tus usuarios a la vez (o a un grupo), con el coste dicho antes de enviar: identidad.txt, «Escribir a todos tus usuarios». **Respuestas guardadas.** Lo que el dev contesta a menudo («Horarios de las clases») lo guarda una vez y lo elige al responder en el panel (Personas › Buzón › Respuestas guardadas, y «Respuestas guardadas ▾» encima de la caja de respuesta). Viven en la configuración de la app, `savedReplies: [{ id, title, text }]` (hasta 50; título de hasta 80 caracteres y texto de hasta 5000), y son de la app, no del borrador: cambian en el acto, en la publicada y en pre, sin publicar nada. El usuario nunca ve la lista, solo el texto que le mandas. Tu IA las lee en `neblla_get_app` (`app.savedReplies`) y las cambia con `neblla_update_app({ savedReplies })`, que reemplaza la lista entera (conserva el `id` de las que se quedan; `null` las borra todas; `invalid_saved_replies` si alguna no cabe): ```javascript // neblla_update_app { appId: 'ABC', savedReplies: [ { title: 'Horarios de las clases', text: 'Las clases son los lunes y miércoles a las 18:00. Se reservan en la app, en Clases.' }, ] } ``` **Gente sin cuenta: el formulario de contacto de tu web.** Quien no tiene cuenta en tu app también puede escribirte, desde un formulario en tu web: un script y un enlace, sin programar nada más. ```html Escríbenos ``` El enlace abre el formulario (email, nombre y mensaje, en el idioma de la página) y el mensaje entra en Personas › Buzón como el de cualquier usuario, en un hilo por email marcado «sin cuenta», con su aviso en Inicio (`inbox_contact`) hasta que lo lees o contestas. Lo que contestas queda guardado en su hilo, pero **no se le envía por email** (decisión de cuota: no pagamos correo a quien no tiene cuenta; el formulario ya se lo dice). Si quieres contestarle, escríbele tú desde tu correo. `neblla_list_communications` marca esos mensajes con `contact: true`. Solo vale desde una página de tu app (sus dominios permitidos, `.neblla.app` o play.neblla.com) y con el módulo `inbox` encendido (si no, `inbox_off`); hay un límite por dirección IP y 200 mensajes al día por app. Alguien sin cuenta no es un usuario: no sale en Personas › Usuarios, ni en los recuentos, ni en las exportaciones, ni le llega «Escribir a todos». Y aunque luego se registre con ese email, su hilo sigue aparte: escribir un email en un formulario no prueba que sea suyo. --- Capítulo comunidad de la guía Neblla — contenido creado y mantenido por los usuarios (entries), búsqueda y moderación. El contrato base está en core.txt; el criterio de cuándo usar Neblla, en empezar.txt. # Comunidad ## Qué es Un espacio de contenido **creado y mantenido por los usuarios** de tu app, mediado por Neblla: partituras, niveles, problemas de ajedrez, recetas, listings… Lo que se publica se llama **entry**. Tú no montas base de datos, ni endpoints, ni panel de moderación: el SDK publica, lista, busca y modera; Neblla almacena, indexa y hace cumplir la autoría. Una entry tiene tres capas: 1. **Payload** — JSON libre que solo tu app entiende. Neblla no lo indexa ni lo interpreta. Lleva un `contentType` (etiqueta libre, p. ej. `"musicxml"` o `"puzzle/v1"`) para que sepas cómo leerlo. Neblla no aloja assets **dentro de una entry**: si quieres una imagen ahí, la codificas en base64 en el payload y pagas su tamaño. (**Para lo que suben los usuarios** —fotos, PDF, audio— conecta el almacenamiento de ficheros que prefieras, como Cloudinary, S3 o R2: el navegador sube el fichero directo allí y la entry guarda solo su URL: con Cloudinary, con un preset de subida; con R2 o S3, con una URL firmada que te da tu Server o una función pequeña tuya, porque se firma con tu clave. Crece sin límite y no ocupa tu almacenamiento ni tu cuota. Los ficheros de la propia app (300 por cuenta gratis, compartidos por sus apps; 600 por proyecto Pro) son para tu código y tus assets.) **Y cuándo eso está bien tiene una regla, porque en pagos.txt te decimos lo contrario y no es una contradicción:** un payload de entry se lee de uno en uno —alguien abre *esa* entry— así que pagas la imagen cuando alguien de verdad la mira. Un catálogo de tienda, en cambio, se pinta entero en cada visita, así que ahí el base64 te cobra todas las imágenes a todo el que entra y la URL externa es la respuesta. Regla corta: **base64 para lo que se abre de uno en uno, URL para lo que se lista.** 2. **Campos indexados** (fijos, de Neblla) — `title`, `summary`, `category`, `tags`, `lang`, `contentType`, `parentId`, `status`, `owner`, `stats`, fechas. Por ellos se lista, busca y ordena. 3. **Relación usuario↔entry** (favorito, valoración, reseña, denuncia, voto, dato privado) — ya está — ver "Favoritas, valoraciones, reseñas y denuncias" y "Votos" más abajo. Requiere el módulo `community` encendido en Config → Módulos (o `neblla_update_app` con `features: { community: true }`). Está **apagado por defecto**: encenderlo implica moderar. ## Modos de moderación (panel: Personas › Comunidad) - **open** — la entry se publica al instante. - **review** — nace `pending`; tú (backoffice) o un moderador de la app la aprueban o rechazan. Si el autor edita una entry publicada, vuelve a `pending`. - **closed** — solo publican los moderadores (tienda curada). Otros ajustes: quién publica (`users` | `moderators`), límite antiabuso de payload por entry (64 KB por defecto; lo ajustas o lo quitas), vocabulario de categorías y de `contentType` (vacío = libre), tope de entries por usuario, texto de reglas. **Las reglas las acepta cada usuario.** Si escribes reglas (`community.rules`), la primera vez que un usuario publica (o edita una entry listada), Neblla le enseña tus reglas en un pop-up pequeño suyo, traducidas a su idioma, y la entry sale cuando las acepta; tú no programas nada. Se guarda la versión que aceptó: si cambias el texto, en su siguiente entry se le vuelven a pedir. Sin reglas no sale nada, las entries privadas no las piden y tú (MCP, tu servidor) tampoco. ### Filtro previo con IA (opcional) `community.prescreen = { mode: 'off' | 'flag' | 'hold', images: false }`. Cuando un usuario publica o edita, la IA integrada lee el título, el resumen y el texto del payload (y, con `images: true`, hasta 3 imágenes en base64 del payload) contra tus reglas. Usa **tu** clave de Claude, la misma de `neblla.ai.prompt()`: cuesta tus tokens y por eso viene apagado. - **`flag`** — la entry se publica igual; si la IA pone pegas, lleva `flagged: { reason }`, visible para todos, para que tu app la difumine o avise antes de enseñarla. Un moderador la limpia con `moderate(id, { action: 'approve' })`. - **`hold`** — si la IA pone pegas, la entry espera en la cola (`pending`) con `moderation.by: 'prescreen'` y el motivo. Si no se pudo comprobar (sin clave, o la IA no respondió), también espera, con `moderation.unavailable: true`: una entry sin revisar no pasa sola. - Una edición se vuelve a revisar entera; si arregla una entry retenida, sale publicada (salvo en modo `review`). Los moderadores y tú no pasáis por el filtro, ni las entries privadas. Estados de una entry: `published` · `pending` · `rejected` · `removed`. Solo las `published` aparecen en `list()`; el autor ve todas las suyas en `mine()` con el motivo de moderación si lo hay. ## Publicar y gestionar lo mío (CLIENT, requiere login) ```js const entry = await neblla.community.publish({ title: 'Where Is My Mind', summary: 'Arreglo fácil para piano', category: 'pop', tags: ['fácil', 'pixies'], lang: 'es', contentType: 'musicxml', payload: { xml: '…' }, }); // entry.status === 'published' (modo open) o 'pending' (modo review) await neblla.community.update(entry.id, { summary: 'Arreglo fácil, dos manos' }); await neblla.community.unpublish(entry.id); // el autor la retira: se borra con sus // reseñas, favoritos y entries hijas. Para corregir una entry, usa update(). En modo // `review`, una edición vuelve a `pending` hasta que un moderador la aprueba. const { entries, next } = await neblla.community.mine(); // todas mis entries, todos los estados ``` Errores (la promesa rechaza con `err.code`): `login_required`, `feature_disabled`, `title_required`, `contentType_required`, `payload_required`, `payload_too_large` (`err.bytes`, `err.max`), `category_not_allowed` / `content_type_not_allowed` (`err.allowed`), `too_many_tags`, `entry_limit_reached`, `moderators_only`, `community_muted`, `community_suspended` (Neblla puso la comunidad en pausa), `community_storage_exceeded` (`err.current`, `err.cap`), `not_owner`, `entry_not_found`, `parent_not_found`, `rules_declined` (cerró el pop-up de las reglas sin aceptarlas), `popup_blocked` (el navegador bloqueó ese pop-up; `err.url` lo abre desde un botón). Evento `neblla.community.on('reportClosed')` `{ entryId, outcome }` (CLIENT): se cerró el caso de una entry que denuncié. `outcome` es `upheld` (se retiró) o `dismissed` (sigue publicada). No trae el mensaje del moderador: ese es para el autor. Evento `neblla.community.on('updated')` `{ entry, action }` (CLIENT): moderación tocó una entry mía. `action` ∈ `published` | `pending` | `rejected` | `removed` | `restored` | `modified` | `suspended`. `entry.moderation` trae `{ reason, message }` escrito por el moderador. ## Hilos, colecciones y versiones `parentId` cuelga una entry de otra. Con un solo mecanismo salen los comentarios (una entry hija con payload de texto), las colecciones y las versiones o remezclas con procedencia. `list({ parent: id })` devuelve las hijas; `list({ parent: null })` solo raíces. La madre suma `stats.children`. El `parentId` se fija al publicar y no cambia. ## Listar, buscar y leer (BOTH — también para invitados) ```js const { entries, next } = await neblla.community.list({ q: 'pixies', // texto libre sobre title/summary/tags category: 'pop', tags: ['fácil'], // todas las etiquetas dadas lang: 'es', contentType: 'musicxml', owner: 'me' | '', parent: null | '', sort: 'recent' | 'oldest' | 'title' | 'popular' | 'top' | 'used' | 'votes', // con q, por relevancia si no indicas sort cursor: next, // paginación opaca; limit ≤ 50 (default 20). Con sort 'recent' u 'oldest' (el feed) pagina por clave: lo que llega entre dos páginas ni repite ni salta; los demás órdenes cambian bajo el lector y paginan por posición limit: 20, }); const facets = await neblla.community.facets(['category', 'tags']); // { category: [{ value, count }], tags: [...] } const { entry, payload } = await neblla.community.get(entryId); // el payload solo aquí ``` `list()` devuelve **solo la capa indexada** más `stats`; el payload se pide entry a entry con `get()`. Cada entry incluye `owner: { id, name, slug }` (nunca el email) y `mine: true` si es tuya. Los tres campos no son de la misma naturaleza y conviene saberlo: **`id` es el userId por app** —el mismo de `neblla_list_users`, así que puedes ir de un usuario a todo lo que publicó sin cruzar nombres— mientras que **`name` y `slug` son la identidad pública de la persona y son las mismas en cualquier otra app Neblla**. Si te importa la privacidad de tus usuarios, ese es el campo que viaja entre apps, no el id (ver identidad.txt). ### Campos propios Además de `category` y `tags`, cada app declara sus campos, con tipo, y filtra por rangos: ```js // una vez: neblla_update_app({ community: { fields: { difficulty: 'integer', bpm: 'number', genre: 'string' }, index: ['difficulty'] } }) await neblla.community.publish({ title, contentType, payload, fields: { difficulty: 3, bpm: 92, genre: 'jazz' } }); await neblla.community.update(id, { fields: { difficulty: 4 } }); const { entries } = await neblla.community.list({ where: { difficulty: { gte: 3, lt: 5 } }, orderBy: '-difficulty' }); ``` - Los campos vuelven en `entry.fields`, en `list`, `get`, `mine` y `publish`. Borrar la entry borra sus campos. - `where` es `{ campo: valor }` o `{ campo: { eq, ne, gt, gte, lt, lte, in } }`, como en las tablas; `orderBy`, `'campo'` o `'-campo'`. Los de `index` van con índice. Con `where` se miran las 1000 primeras filas que cumplen la condición; `q`, `tags`, `parent`, `category` y los demás filtros siguen valiendo. `sort` junto a `orderBy` es el error `sort_with_orderBy` (el orden lo da `orderBy`); con solo `where`, manda `sort`. - Errores: `unknown_field` (no está declarado) e `invalid_field_value` (no es de su tipo). - **Estado oficial, solo lo escribe el equipo.** `community.fieldRules: { status: { who: 'moderators', values: ['nueva','planeada','hecha'], stamp: 'statusAt' } }` (para campos que declaraste): solo los moderadores (y tú) escriben ese campo, y solo con valores de la lista cerrada `values` (cadenas); `stamp` nombra un campo `date` que se pone a «ahora» cada vez que se escribe este (el «desde cuándo»). Quien lo intente sin serlo recibe `field_moderators_only` (`err.field`); un valor fuera de la lista, `invalid_field_value` (`err.allowed`). Un foro de soporte, una hoja de ruta o un mercadillo («vendido») son lo mismo. - **Lectura pública con tus campos.** `GET /api/community/public//entries?where={"status":"planeada"}&orderBy=-statusAt` (`where` como JSON, hasta 500 caracteres, solo campos declarados; un JSON roto es `invalid_where`). - **Quién publica en qué categoría.** `community.categoryPublishers: { noticias: 'moderators' }`: los usuarios siguen publicando en las demás categorías y solo el equipo escribe en esa (`moderators_only`, también cuando una edición mueve una entry a ella). - **Traducir al publicar.** `community.autoTranslate: true`: una entry que sale publicada sin traducciones recibe su título y resumen traducidos a los demás idiomas de Neblla en segundo plano, con la clave de Neblla (nunca la tuya). Si falla, la entry se queda en su idioma; nunca bloquea la publicación. Si el autor corrige el título o el resumen, se vuelve a traducir en segundo plano (a no ser que la edición traiga sus propias traducciones): lo que lee cada idioma es el último texto del autor. - Con BYODB, en tu base de datos. ### Una entry en varios idiomas `title`, `summary` y `lang` son el texto propio de la entry. Para que se lea en otros idiomas, publícala (o actualízala) con `i18n`: ```js await neblla.community.publish({ title: 'Ajedrez', summary: 'Juega contra tus amigos', lang: 'es', i18n: { en: { title: 'Chess', summary: 'Play against your friends' }, fr: { title: 'Échecs' } }, contentType: 'app', payload: { … }, }); const { entries } = await neblla.community.list({ q: 'echecs', locale: 'fr' }); const { entry } = await neblla.community.get(id, { locale: 'pt-BR' }); ``` - La búsqueda (`q`) encuentra la entry por las palabras de **cualquiera** de sus idiomas, y el filtro `lang: 'fr'` la encuentra si está en francés **o** traducida al francés. - Con `locale`, `list` y `get` devuelven `title`/`summary` en ese idioma si la entry lo tiene (primero el exacto, `pt-br`; luego el base, `pt`), y si no, el texto propio. Cada entry dice en `shownLang` en qué idioma está lo que ves y en `langs` todos los que tiene. Una traducción sin `summary` muestra el propio. - `get` trae además `text` (el texto propio) e `i18n` entero, para editarlo. En `update`, `i18n` **sustituye** el mapa completo; `i18n: null` lo vacía. - Hasta **16 traducciones**, con los mismos topes que el texto propio (`title` 120, `summary` 500). Errores: `invalid_i18n`, `invalid_i18n_lang` (código no válido: `fr`, `pt-br`, `zh-hant`), `too_many_translations` (`err.max`). ### Imagen de la tarjeta `image` es una URL `https://` (hasta 512 caracteres) que viaja con la entry en `list`, para pintar tarjetas sin pedir el payload de cada una. Opcional; `invalid_image` si no es una URL https. Neblla no la descarga ni la aloja: apunta a donde ya esté la imagen. ### Lectura pública por HTTP Lo publicado se puede leer sin arrancar el SDK, para la primera pintura de una página, un render en servidor o un buscador. Sin login y con CORS abierto: ``` GET /api/community/public//entries?q=&category=&tags=a,b&lang=&contentType=&parent=null&sort=&cursor=&limit=&locale= GET /api/community/public//entries/?locale= → { entry, payload } GET /api/community/public//entries//reviews?cursor=&limit= GET /api/community/public//facets?fields=category,tags ``` Mismas respuestas que `list`, `get`, `reviews` y `facets` para un invitado: solo entries publicadas y ninguna relación de nadie (no hay lector). Cuesta la misma cuota que la lectura por el SDK, pero las respuestas salen unos segundos de una caché: una página muy visitada que pide la misma lista paga una lectura por intervalo, no una por visitante. Errores: `404 feature_disabled` (la app no tiene comunidad), `404 entry_not_found`, `403 community_suspended`, `429` sin crédito. Para escribir, el SDK o tu servidor (`/api/backend/apps//community/{publish,update,delete}`, ver mcp.txt). Desde los ficheros de `server/` (`neblla` global) solo existen `community.list`, `community.facets` y `community.get`: Fog es el navegador de otro usuario y **nunca** publica ni modera en nombre de nadie. ## Favoritas, valoraciones, reseñas y denuncias (CLIENT, requiere login) Cada usuario tiene **una relación** con cada entry publicada. `visibility` tiene tres valores: - **`'public'`** (por defecto): la ve cualquiera, también los invitados y la lectura pública por HTTP. Sin cifrado. - **`'protected'`**: la ve un **grupo**. Los dueños de la entry son sus administradores, los editores que nombren pueden leerla y escribirla, y los moderadores de la app (el dev lo es siempre) pueden leerla, por ejemplo para aprobarla antes de hacerla pública. Va cifrada con una clave del grupo y no aparece en listados ni búsquedas de quien no esté en él: `publish({ …, visibility: 'protected', group: { editors: [userIdA, userIdB] } })`, y el grupo se cambia con `update(id, { group })`. - **`'private'`**: solo su autor. Su contenido (el payload) va **cifrado de extremo a extremo**: se cifra y se descifra en el navegador, y ni Neblla puede leerlo. El título, el resumen y las etiquetas van en claro, para que el autor pueda listar las suyas: no pongas ahí nada privado. Para abrirla en otro dispositivo tuyo o dársela a otra persona, se usa un enlace con clave (ver "Compartir en privado por enlace"). Cambiar de visibilidad conserva el grupo y sus roles, así que una entry puede pasar de protegida a pública y volver sin reconfigurar a nadie. Si moderación la retira, una entry **bloqueada** o **baneada** la siguen viendo sus dueños, el dev y los moderadores (nadie más); si era privada, tampoco ellos pueden leer su contenido, y solo su dueño puede quitarle el cifrado personal y pasarla a protegida. **Ojo a los nombres de campo, cambian entre escribir y leer.** El texto se escribe con `relate(id, { review: 'Preciosa' })`, pero `reviews()` devuelve cada una como `{ author, rating, text, at, mine }` — el texto llega en **`text`**, no en `review`. Pintar `r.review` te da una lista vacía y ningún error. **Topes de los campos indexados** (pasarse rechaza la publicación): `title` 120 caracteres, `summary` 500, `category` 40, **20 tags máximo** de 32 caracteres cada uno (`too_many_tags` lleva `max`), `lang` 8. `maxEntriesPerUser` vale **0 por defecto, que significa sin límite** (hasta 10.000); `reportThreshold` vale 3 por defecto (hasta 1000) y se configura en el `community` de la app. Escribirla es un merge parcial: tocar la favorita no borra la valoración. ```js await neblla.community.relate(entryId, { favorite: true }); const { relation, stats } = await neblla.community.relate(entryId, { rating: 4, review: 'Muy bonita', locale: 'es' }); // locale (opcional): el idioma en que está escrita la reseña; reviews() lo devuelve en `lang` // relation = { favorite, rating, review, reported, vote } · null borra una ranura: { rating: null } // stats = { favorites, ratingCount, ratingSum, ratingAvg, reviews, reports, children, uses, upvotes, downvotes, score } const mia = await neblla.community.relation(entryId); // mi relación con esa entry const { entries, next } = await neblla.community.favorites(); // mis favoritas publicadas const { reviews, next: n2 } = await neblla.community.reviews(entryId); // BOTH: reseñas públicas, recientes primero // reviews[i] = { author: { id, name, slug }, rating, text, at, lang?, mine, reply } reply = { text, at } | null await neblla.community.reply(entryId, reviews[0].author.id, '¡Gracias! Más niveles pronto'); // el autor de la entry responde (null la retira) await neblla.community.report(entryId, { reason: 'copyright', message: 'Es un arreglo con derechos.' }); // → { ok, suspended } reason ∈ copyright | inappropriate | hate | harassment | spam | illegal | privacy | other ('other' exige message) ``` - `list()`, `get()`, `mine()` y `favorites()` traen en cada entry `me: { favorite, rating, review, reported, vote }` si hay login: pintas "mis estrellas" sin una llamada por fila. `sort: 'popular'` ordena por favoritas, `'top'` por valoración media, `'used'` por usos y `'votes'` por votos. - **Responder reseñas.** El autor de la entry responde cada reseña con `reply(entryId, reviewerId, texto)`, donde `reviewerId` es el `author.id` de la reseña; también pueden los moderadores, y el dev desde su servidor (`POST /api/backend/apps//community/reply`) o el MCP. Una respuesta por reseña: la nueva sustituye a la anterior y `null` la retira. Sale bajo la reseña en `reviews()` como `reply` y, para quien reseñó, en su `relation()`. Si retira su reseña, la respuesta se va con ella. Errores: `not_author`, `review_not_found`, `reply_too_long` (1000 caracteres). - **Usos.** Cada entry lleva `stats.uses`, que solo suma su dueño desde su servidor: `POST /api/backend/apps//community/uses` con `{ entryId, n }` (por defecto 1). `sort: 'used'` lo lee: «más jugadas», «más descargadas», «más abiertas». - El autor no puede valorar, reseñar ni denunciar su propia entry (`own_entry`); sí marcarla como favorita. - Una denuncia por usuario y entry (`already_reported`), máximo 20 al día por cuenta (`report_limit_reached`). El autor nunca sabe quién denunció; el dev lo ve como id opaco. - Al llegar a `community.reportThreshold` denunciantes distintos (por defecto 3; 0 = nunca) la entry se auto-suspende: su `status` pasa a **`pending`** (no a `suspended`), desaparece del listado y el autor recibe `community.on('updated')` con `action: 'suspended'`. Eso importa al trabajar la cola: en `pending` conviven las entries que esperan primera aprobación y las que han caido por denuncias — distínguelas por `moderation.by`, que vale `'reports'` en las automáticas. El status `suspended` es el que pone un moderador a mano mientras hay un caso abierto. Aprobarla o restaurarla desestima las denuncias; retirarla las da por buenas. No todas las denuncias pesan igual para ese umbral: quien acumula denuncias desestimadas cuenta menos — la mitad si tiene más desestimadas que confirmadas, y nada si tiene 3 o más desestimadas y ninguna confirmada (su denuncia queda igualmente registrada para el moderador). Nadie cuenta más de uno. - Un usuario silenciado (`community_muted`) no puede relacionarse con entries, pero sí denunciar. ### Votos Cada usuario con login da **un voto por entry**: a favor y, si tu app lo enciende, también en contra. Sirve para todo lo que se elige entre muchos: en una app de vecinos, cada propuesta («poner bancos en la plaza») tiene sus votos y salen primero las más votadas; igual las ideas de un foro, las recetas o las sugerencias de un curso. ```js await neblla.community.vote(entryId); // a favor (lo mismo que vote(entryId, 1)) await neblla.community.vote(entryId, -1); // en contra: solo con community.downvotes: true const { vote, stats } = await neblla.community.vote(entryId, null); // quitarlo (0 también) // stats = { …, upvotes, downvotes, score } score = a favor − en contra const { entries } = await neblla.community.list({ sort: 'votes' }); // las más votadas primero // entries[i].stats.score, y entries[i].me.vote = 1 | -1 | null con login ``` - Votar otra vez cambia el voto, no suma otro. También vale `relate(entryId, { vote })`. - El voto en contra está **apagado por defecto**: actívalo con `neblla_update_app({ community: { downvotes: true } })` o en el panel (Personas › Comunidad, «Votos en contra»). Sin él, `vote(id, -1)` rechaza con `downvotes_off`. Apagarlo después hace que los votos en contra que ya hay dejen de contar: `downvotes` sale 0, `score` es solo los votos a favor y `sort: 'votes'` ordena por ellos. No se borran: si lo vuelves a encender, vuelven a contar. Quien votó en contra sigue viendo su `me.vote: -1` y puede retirarlo con `vote(id, 0)`. - `sort: 'votes'` ordena por `score`; a igual `score`, la que tiene más votos a favor. - El autor no vota lo suyo (`own_entry`). Un voto que no es `1`, `-1`, `0` ni `null` da `invalid_vote`. - **Nadie ve quién votó**: ni el autor, ni los demás, ni el dev. Solo los recuentos y, cada uno, su propio voto en `me.vote`. - **Los votos de un usuario baneado no cuentan.** Al banearlo (*banned* o *terminated*) sus votos salen de los recuentos, y vuelven si levantas el baneo. Uno silenciado (`community_muted`) no puede votar, pero lo que ya votó sigue contando. Si lo borras de tu app, sus votos se van con él. - Cuesta lo mismo que una favorita: `community_query` por voto. ## Compartir en privado por enlace (CLIENT, requiere login) Una entry **privada** no aparece en `list`, `facets` ni búsquedas, y va cifrada de extremo a extremo. Un **enlace con clave** la abre: el enlace lleva la clave de descifrado detrás de `#`, que el navegador nunca manda al servidor, así que quien tiene el enlace la lee y Neblla sigue sin poder. Sirve para mandar algo a una persona concreta (por WhatsApp, email…) sin publicarlo. ```js // 1. El autor crea la entry privada (no pasa por la cola de revisión) y un enlace const e = await neblla.community.publish({ title: 'Para Gonzalo', contentType: 'partitura', payload, visibility: 'private' }); const { token, key, expiresAt } = await neblla.community.shareLink(e.id, { uses: 1, // aperturas permitidas (1 = una sola descarga; máx. 100) expiresInDays: 10, // caducidad (máx. 30) deleteEntry: true, // al gastarse el último uso (o caducar) se borra también la entry }); const url = location.origin + location.pathname + '?envio=' + token + '#k=' + key; // la clave, detrás de '#' // 2. Quien lo recibe abre la app con ese enlace, entra con Neblla y: const { entry, payload } = await neblla.community.openLink(token, key); // gasta un uso; descifra en su navegador ``` - El token son 256 bits aleatorios (base64url, 43 caracteres); Neblla guarda solo su SHA-256, así que tu base de datos nunca contiene un enlace utilizable. - `openLink` exige sesión (`login_required`). Una entrada que la moderación esconde (`suspended`, `pending`) no se comparte (`shareLink` → `entry_not_visible`) ni se abre por un enlace viejo (`link_not_found`, sin gastar el uso). Un enlace desconocido, gastado o caducado responde siempre `link_not_found`, sin pistas. - Solo el autor puede crear enlaces de su entry (`not_owner`). Funciona igual con entries públicas (`deleteEntry: false`). - Los enlaces viven en la tabla `community_links` de tu base de datos (BYO-DB), como el resto de la comunidad. La clave no se guarda en ninguna parte: si se pierde el enlace, se crea otro. - **Tus otros dispositivos.** El mismo mecanismo abre tus entries privadas en otro navegador tuyo: `const { url } = await neblla.community.deviceLink()` da un enlace (o un QR) con tu clave personal; ábrelo en el otro dispositivo, con tu misma cuenta, y desde entonces ese navegador lee todas tus entries privadas. El enlace nunca pisa una clave que el navegador ya tuviera: la guarda aparte y sigue abriendo lo que sellaba. - **Una sola clave por usuario y app.** Neblla guarda solo la huella de tu clave personal (16 bytes de su SHA-256; no permite reconstruirla). Un navegador sin tu clave no se inventa otra: `publish` privada y `deviceLink()` fallan con `key_unavailable` hasta que le llegue la tuya, y un bloque sellado con otra clave se rechaza (`key_mismatch`). Así, usar la app desde un segundo navegador no deja entradas ilegibles. ### Ver y revocar mis enlaces ```js const mis = await neblla.community.links(); // o links({ entryId }) para una entry // → [{ id, entryId, usesLeft, expiresAt, createdAt, deleteEntry }], los más nuevos primero await neblla.community.revokeLink(mis[0].id); // → { revoked: true } ``` - `id` es el hash del token: sirve para revocar, pero no abre nada. El token en sí no se puede recuperar. - Solo el autor ve y revoca sus enlaces (`not_owner`); un `id` desconocido → `link_not_found`. ### Tarjeta pública de una entry Para que un usuario pegue una entry en Discord, WhatsApp o X: ```js const url = neblla.community.cardUrl(entry.id); // https://play.neblla.com/c// // … y al cargar tu app: const id = neblla.community.linkedEntry(); // el id si se llegó por una tarjeta, si no null if (id) { const { entry, payload } = await neblla.community.get(id); /* ábrela */ } ``` - La vista previa del chat sale de las etiquetas Open Graph: título, resumen e `image` de la entry (sin `image`, la portada de la app) y el nombre de la app. No lleva el payload ni lo lee. - Quien hace clic llega a tu app con `?entry=`; `linkedEntry()` lo lee (y descarta lo que no tenga forma de id). - Solo tienen tarjeta las entries publicadas. Una privada, pendiente, retirada o inexistente da el mismo 404: el enlace no revela que exista. Para compartir una privada, `shareLink`. - Revocar el último enlace de una entry creada con `deleteEntry: true` la borra también, igual que al gastarse. - Los enlaces caducados o gastados se limpian solos (con su entry desechable) cada vez que la app crea o lista enlaces. ## Moderar desde la app (CLIENT, solo moderadores de la app) **Quién modera.** Los moderadores de la app son los miembros de su grupo reservado `moderators` (identidad.txt, «Grupos y permisos»), por su id de usuario en la app: los nombras y los quitas desde el panel (Personas › Moderación), con `neblla_set_moderator` o, con el módulo de grupos, desde la API de administración y tu servidor (`group: 'moderators'`). El grupo vive en los datos de la app (con BYODB, en tu base), así que sigue a los datos como los usuarios: pre con los datos de pro modera con los de pro; pre con sus propios datos tiene su grupo, vacío al empezar: añádete con tu usuario de pre (`neblla_set_moderator` con `env: 'pre'`, o el back office en pre) o añade a quien quieras, y moderas allí sin tocar pro. ```js const { entries } = await neblla.community.queue({ status: 'pending' }); await neblla.community.moderate(entryId, { action: 'approve' }); await neblla.community.moderate(entryId, { action: 'reject', reason: 'copyright', message: 'Partitura con copyright vigente.' }); // action ∈ approve | reject | remove | restore | suspend // reason ∈ copyright | inappropriate | hate | harassment | spam | illegal | privacy | other ``` `reject` y `remove` exigen `reason`; el autor recibe `community.on('updated')` con el motivo y el mensaje. `remove` conserva la entry y su payload (para apelar por la bandeja dev↔usuario); `restore` la devuelve a `published`. El backoffice del dev portal tiene la misma cola con contadores por estado, y el detalle de cada entry muestra sus denuncias agregadas por motivo. Sobre el autor, desde la ficha del usuario en el backoffice: **silenciar en la comunidad** (`community_muted`: sigue usando la app, no publica ni edita), *banned*, *terminated*. **La cola viene por gravedad.** Las entries `pending` y `suspended` llegan primero las más serias y, dentro de cada nivel, la más antigua primero; cada una trae `priority`: `notice` (aviso legal formal) > `serious` (ilegal, copyright, privacidad, odio o acoso) > `reports` (suspendida por denuncias) > `prescreen` (retenida o marcada por el filtro previo) > `review` (espera aprobación). `queue({ status: 'pending', sort: 'oldest' })` da el orden de llegada sin más. **Reincidencia.** `community.recidivism = { removals: 3, days: 30 }` (valores por defecto; `removals: 0` lo apaga): cuando a un mismo autor le retiran (`remove`) `removals` entries en `days` días, queda silenciado en la comunidad solo (`community_muted`, con `communityMutedBy: 'recidivism'`); `moderate` devuelve entonces `authorAction: 'muted'`. Si estando silenciado llega al doble, su ficha del backoffice y `neblla_list_users` muestran `banSuggested: true` (`authorAction: 'ban_suggested'`). Neblla nunca banea ni cierra una cuenta por su cuenta: esa decisión es tuya, y en cuanto cambias su estado la sugerencia desaparece. ## Notificaciones formales desde fuera de la app Cualquiera —sin cuenta y sin ser usuario de la app— puede presentar una notificación formal sobre una entry publicada: un titular de derechos o quien detecte contenido ilegal. El formulario está en `/notice?app=&entry=` y pide lo que exige un procedimiento de retirada: identidad y contacto del reclamante, la obra afectada, una declaración de buena fe y una firma. Presentarla suspende la entry al momento (`status: 'suspended'`, `moderation.by: 'notice'`, con `moderation.caseId`) y abre un caso. Te llega un email avisando de que hay un caso esperando; la reclamación, con los datos del reclamante, está en el detalle de la entry en el panel (Personas › Comunidad, filtro **Suspendidas**), donde la das por buena o la desestimas, y por MCP como `neblla_community_cases`. Al autor se le avisa por `community.on('updated')` y puede contra-notificar desde tu app: ```js await neblla.community.counterNotice(entryId, 'La compuse yo en 2023; aquí está el proyecto original.'); // → { cases: [{ caseId, status: 'countered' }] } solo el autor; errores: case_not_found, not_the_author, missing_field ``` El reclamante recibe la respuesta por email. Una contra-notificación **no** restaura la entry por sí sola, y cerrar un caso tampoco la vuelve a publicar: restaurar es un acto aparte y deliberado, para que ni una respuesta ni un clic sin querer devuelvan algo. Para poner un enlace de "denunciar un problema legal" en tu propia interfaz, `neblla.community.noticeUrl(entryId)` da la dirección del formulario para esa entry; la tarjeta pública de la entry (`cardUrl`) también enlaza a él. Como las notificaciones formales van dirigidas a Neblla como plataforma, Neblla también puede actuar por su cuenta: suspender o restaurar una entry (queda `moderation.by: 'platform'` y encabeza la cola) o poner en pausa la comunidad entera de una app. Durante la pausa los usuarios no pueden publicar, leer ni relacionarse con entries (`community_suspended`) y la tarjeta pública no se ve; tú recibes un email con el motivo, el backoffice lo muestra (y `neblla_get_community_config` trae `platformHold`), y sigues pudiendo revisar y moderar. Tu app sigue funcionando. ## Cuota y almacenamiento Publicar y editar cuestan cuota por bytes (`community_publish`); leer un payload cuesta sus bytes (`community_read`); listar, facetas, `mine`, la cola y cada favorita, valoración o voto tienen coste fijo (`community_query`). La comunidad comparte la base de datos de la app con los datos de usuario (50 MB por cuenta en gratis, compartidos por sus apps; 100 MB por proyecto Pro): al llenarse, `publish`/`update` rechazan con `community_storage_exceeded`. Todo el contenido de la comunidad es tuyo y vive en la base de datos de tu app: con BYO-DB, en **tu** base de datos (Turso, Postgres, MySQL o Mongo); sin él, en el Turso por defecto de Neblla. Tablas: `community_entries` (metadatos indexados, estado, moderación y contadores), `community_entry_tags`, `community_relations` (favoritas, valoraciones, reseñas, denuncias, votos), `community_links` (enlaces de compartir, solo el hash) y `community_payloads` (el payload); en Mongo, las colecciones `neblla_community_*`. Neblla solo guarda en su base la configuración de la app, el contador de almacenamiento y la identidad de los usuarios. Las entries de un usuario se borran cuando se borra al usuario de tu app (lo pide él, o lo haces tú desde el backoffice o con el MCP). Si borra su cuenta de Neblla, no: su fila en tu app y lo que publicó se quedan, sin cuenta Neblla detrás. ## Un ranking con comunidad Una tabla de puntuaciones se monta con entries de comunidad y un campo propio para ordenar: ```javascript // una vez: neblla_update_app({ community: { fields: { puntos: 'integer' }, index: ['puntos'] } }) // al acabar una partida, en client.js await neblla.community.publish({ title: nombre, category: 'score', contentType: 'score', lang: 'es', fields: { puntos }, payload: { at: Date.now(), segundos } }); // la tabla, legible también por invitados const { entries } = await neblla.community.list({ contentType: 'score', orderBy: '-puntos', parent: null, limit: 20 }); ``` Así la puntuación la publica el propio jugador y nadie la comprueba: vale para un ranking entre amigos sin nada en juego. Para uno que no se pueda falsear, `neblla.scores` (ver identidad.txt): la partida empieza en Neblla y lo imposible no entra. Usa `mode: 'open'` en la configuración de comunidad, para que cada puntuación se publique al momento en vez de pasar por la cola de revisión. Y si el ranking tiene que vivir con el resto de tus datos, `neblla_byodb` pone los datos de comunidad en tu propia base de datos, donde puedes consultarlo también con tu propio SQL. ## Un espacio compartido más grande que una sala Un documento que edita un equipo —un tablero, un documento colaborativo, el inventario de una partida larga, una wiki interna— vive aquí y no en `room.data`, que es para el estado de la sala. Una entry admite **64 KB de payload por defecto**, un límite antiabuso que cambias a lo que necesites con `neblla_update_app({ community: { maxPayloadBytes: 262144 } })`, o quitas con `maxPayloadBytes: 0`. La base de datos (50 MB por cuenta gratis, compartidos por sus apps; 100 MB por proyecto Pro, o la tuya con BYODB) da para unas ochocientas entries de 64 KB en gratis, y por defecto no hay tope de entries por usuario (`maxEntriesPerUser: 0`). Requisitos: el módulo `community` (`features: { community: true }`) y login. Los invitados leen; escriben los usuarios con login. **Solo para el equipo.** Publícalas `visibility: 'protected'` con el equipo como grupo, y lo interno del equipo no lo ve nadie más de la app. **Una entry por miembro.** Escribir en una entry es cosa de su dueño, de los editores de su grupo (si es `protected`) o de un moderador de la app. Aun así, para el estado de un equipo, dale a cada miembro su propia entry con una `category` común, y el estado del equipo es la **unión** de todas, que cualquiera lee con `community.list({ category })`. Así no hay conflictos de escritura por construcción, nadie necesita poderes de moderación, y quién cambió qué sale gratis porque cada trozo lleva su `owner`. **La sala avisa, comunidad guarda.** Para que los demás vean un cambio al momento, quien escribe hace su `community.update(...)` y manda un `message.send` a la sala con el id de la entry; los demás releen solo esa entry con `community.get(id)`. Por la sala solo viajan punteros de decenas de bytes, así que el tamaño del documento no depende del de la sala. **Lo que cuesta.** Publicar o actualizar cuesta los bytes del payload; leer una entry, la petición como un mensaje (64 + sus bytes) y la entry como respuesta (64 + sus bytes); un `list` o un `facets`, **50 unidades** fijas más la lista; y el aviso por la sala, su tamaño. Parte el estado del equipo en entries por miembro o por sección y relee solo la que cambió. BBDD propia con `neblla_byodb` mueve la base de datos a tu proveedor; el tráfico de comunidad se cuenta igual. --- Capítulo pagos de la guía Neblla — productos, checkout Stripe, validación y consumo. El contrato base está en core.txt; el criterio de cuándo usar Neblla, en empezar.txt. # Compras Integración con Stripe. El desarrollador no procesa pagos, no monta endpoints de Stripe, no gestiona los webhooks de Stripe. Si quiere enterarse de cada compra en su propio sistema (un n8n, un CRM), el webhook saliente `purchase` de Neblla se lo manda (ver core.txt). Cuatro tipos de producto: `one_time`, `consumable`, `subscription` (mensual o anual, con prueba gratis si quieres) y `donation` (importe libre que elige quien da, ver «Donaciones»). Los tres son **entitlements dentro de la app** — un permiso o un contador atado a un usuario — y un producto único o un consumible puede además ser un **fichero a la venta** (una foto en alta resolución, un PDF, un pack de texturas: "Ficheros a la venta" más abajo), tener **unidades a la venta** (una edición de 10, "Unidades a la venta") o ser **físico**, enviado con sus gastos de envío y seguido como pedido ("Productos físicos y pedidos"). En el **pre** de la app las compras van, por defecto, por el modo de prueba de Stripe: nada se cobra y pro no las cuenta (ver publicar.txt, «Las compras en pre»). ## API `neblla.shop.purchases` es un **objeto indexado por id de producto**, no un array — `{}` si el usuario no tiene nada. Comprueba la propiedad con `neblla.shop.purchases['pack_invierno']`, nunca con `.some(...)`. ```javascript neblla.shop.products(); // listar lo que tienes en venta neblla.shop.buy('skin_dorado'); // abre checkout de Stripe neblla.shop.buy('monedas_pack', 100); // consumible con cantidad neblla.shop.consume('monedas_pack', 10); // consumir unidades neblla.shop.buy('premium'); // suscripción: se renueva sola neblla.shop.manage('premium'); // cancelar, cambiar la tarjeta, ver facturas neblla.shop.validate(userId, 'vip_pass'); // verificar (también desde el servidor) ``` Firmas: - `neblla.shop.buy(productId, amount?, { country }?)` **(CLIENT; un invitado compra con la cuenta ligera, ver identidad.txt, "Cuenta ligera")** — abre el checkout de Stripe en una ventana. Llámalo dentro del gesto del usuario (un click) para que el navegador no bloquee la ventana. La promesa se resuelve cuando la ventana está abierta, NO cuando se ha pagado: lo comprado llega después con `neblla.shop.on('purchase')`. Si apagaste la cuenta ligera, a un invitado le pide hacer login en esa misma ventana y sigue con el pago en cuanto entra; si cierra la ventana sin entrar, rechaza con `login_required`. Rechaza con el código del servidor (`feature_disabled`, …). Si el navegador bloquea la ventana, rechaza con `popup_blocked` y trae la `url` del checkout: pinta un botón que la abra — ese clic es un gesto nuevo y el navegador sí lo deja. Los datos de tarjeta nunca pasan por el código de la app. Los productos no se pueden comprar hasta que la cuenta de cobros del dev (Stripe Connect) está activa. - `neblla.shop.consume(productId, amount)` **(CLIENT)** — consume unidades. - `neblla.shop.validate(userId, productId)` **(BOTH)** — verifica posesión. También se puede llamar desde `room.js`, útil para gatear acciones autoritarias detrás de tener un producto: por ejemplo, para entrar en la sala VIP, `room.js` comprueba que el usuario tiene `vip_pass` antes de dejarle pasar, sin que pueda falsificarlo desde su cliente. - `neblla.shop.products()` **(BOTH)** — lista productos. Uno que espera a la cuenta de cobros sale con `waiting: true`: píntalo como «próximamente», sin botón de compra; se pone a la venta solo en cuanto la cuenta está activa. - **El nombre de un producto.** `neblla_create_product` acepta `productId: 'premium'` (2-40 caracteres `a-z 0-9 _ -`, único en la app; `product_id_taken` si ya existe): es el nombre que escribe tu código, y todos los ejemplos de esta guía (`shop.buy('premium')`, `shop.validate(userId, 'vip_pass')`) lo usan. El producto sigue teniendo un id hex que Neblla pone; el catálogo trae los dos (`productId` y `slug`) y `buy`, `manage`, `consume`, `validate` y `shop.purchases['premium']` aceptan cualquiera. Sin él, el nombre es el hex que devuelve la tool. Los ajustes `trade.products` y `business.booking.*.product` piden el id hex. - **Cuando una compra no sale.** Todo error de `shop.buy` y `shop.manage` trae un `code` para decidir qué decirle al usuario (un juego, una app o una web, el mismo `code`): `product_waiting` (aún no se vende: «pronto»), `product_not_published`, `product_not_found`, `invalid_amount` (con `min`, `max` o `step`), `payouts_not_ready` y `stripe_test_account_required` (el dev aún no puede cobrar), `not_connected`/`login_required` (que entre), `feature_disabled`, `popup_blocked` (con la `url`), `checkout_failed` (cualquier otro); en `manage`, `not_subscribed` y `portal_failed`. Con `test: true` el fallo es del modo de prueba. Ejemplo: `try { await neblla.shop.buy('bono_10') } catch (e) { aviso(e.code === 'product_waiting' ? 'Muy pronto a la venta' : e.code === 'popup_blocked' ? botonQueAbre(e.url) : 'No se ha podido abrir el pago') }`. - `neblla.shop.testMode` **(CLIENT)** — `null` cuando se cobra de verdad; `{ card }` cuando la app vende en el modo de prueba de Stripe (el pre, o una app de ejemplo, de slug acabado en `-example`): nada se cobra y `card` es la tarjeta de prueba que paga. Díselo al visitante junto al botón de compra. - `neblla.shop.manage(productId)` **(CLIENT, login)** — abre el portal de Stripe del suscriptor, donde cancela, cambia la tarjeta o descarga sus facturas. Mismas reglas de ventana que `shop.buy`. - `neblla.shop.orders()` **(CLIENT, login)** — los pedidos de productos físicos del propio usuario, los más nuevos primero: `[{ id, productId, productName, units, status, zone, shipping, carrier?, tracking?, trackingUrl?, history, withdrawal, refunded? }]` ("Productos físicos y pedidos" más abajo). - **Pasar lo comprado a otro usuario:** si pones un producto de un solo pago o consumible en `neblla_update_app({ trade: { products: [...] } })`, sus unidades se pueden intercambiar con `neblla.db.offer` (ver identidad.txt, «Intercambios entre usuarios»). El pago se queda con quien pagó: lo que recibe el otro no es una venta (no sale en Ventas ni se reembolsa), y los dos oyen `purchase` con `type: 'trade'`. Una suscripción no se intercambia nunca. ## Evento purchase Cuando la compra se confirma, el evento `neblla.shop.on('purchase', cb)` (`{ userId, productId, slug?, type, purchases }`; `slug` es el nombre que le diste con `productId` al crearlo: `p.slug === 'premium'`) se dispara en los dispositivos del comprador, y solo en los suyos: lo que tiene cada usuario es suyo y no viaja a la sala. Útil para reaccionar en tiempo real (animación, desbloqueo del skin). Si otros tienen que ver algo que alguien compró (su skin, su insignia), que lo anuncie tu código con un mensaje y que `room.js` lo compruebe con `neblla.shop.validate(userId, productId)`: solo el servidor de la sala puede mirar lo de otro usuario. Desde un cliente, `validate` mira lo del propio usuario, y por otro responde `{ valid: false, error: 'not_allowed' }`. **Al volver:** si el móvil se bloqueó, la página pasó a segundo plano o salió a pagar en la ventana de Stripe, lo que se compró mientras tanto no llegó por el socket. Al volver el SDK repide las compras él solo y, si cambiaron, dispara `shop.on('purchase')` con `type: 'sync'` y los `purchases` al día (igual que en el Login): no hace falta recargar. Lo mismo con el saldo de fichas (`tokens`) y con las reservas y los bonos (`business.booking.on('update')`, `business.credits.on('update')`) si la página los había consultado. **Ojo con el Login:** al hacer Login el SDK dispara ese mismo evento una vez con `type: 'sync'` (sin `productId`) y todas las compras de la cuenta en `purchases`. No es un pago nuevo: úsalo para pintar lo que ya tiene, y anuncia «pago recibido» solo cuando llegue un `productId` y `type` no sea `'sync'`. **Trampas.** El SDK compara de vez en cuando las compras del dispositivo con las del servidor: si tiene menos (una pestaña vieja), se corrige y ya está; si dice tener más de lo que compró, se corrige, el usuario recibe una marca (la columna de marcas del backoffice) y lo ves en el panel, Personas › Moderación, con lo que decía tener y lo que tiene de verdad. Es un aviso: no se le hace nada más. Si la venta se **reembolsa entera** desde Stripe, o el comprador abre una disputa y **la pierdes** (contracargo), la compra deja de contar en todas partes y, si el usuario está conectado, llega otro `shop.on('purchase')` con `type: 'revoked'` y los `purchases` ya actualizados: quita lo que desbloqueaba. Un reembolso parcial solo queda anotado; qué unidades cubre lo decides tú. Mientras una disputa está abierta, o si la ganas, el usuario conserva lo comprado. **Tus ventas, en el panel.** Dinero › Ventas lista cada compra con lo pagado, su estado y quién la hizo. Desde una venta puedes **reembolsarla** entera (vuelve el dinero en Stripe, con la comisión de Neblla, y la compra se retira al momento como arriba; una suscripción no se reembolsa ahí: se reembolsa o se cancela en tu panel de Stripe, y su venta trae el enlace, «Abrir en Stripe», `stripeUrl`) y abrir **el recibo o las facturas** de Stripe de esa compra (los enlaces que da Stripe; Neblla no guarda PDFs). Las ventas (con el id, el email y el nombre del comprador) y tus usuarios se descargan en **CSV**. Por el MCP, `neblla_sales`; por HTTP, `POST /api/backend/apps//sales` (y `/sales/csv`, `/sales//refund`, `/sales//documents`, `/users/csv`) con tu `authToken`. Propiedad: `neblla.shop.purchases` **(CLIENT)** — las compras del usuario. ## Suscripciones Para un plan premium que se paga cada mes o cada año. El producto lleva `type: 'subscription'`, el precio por periodo, `interval: 'month' | 'year'` y, si quieres, `trialDays` de prueba gratis. Se vende igual: `neblla.shop.buy('premium')`. - **Mientras está pagada (o en prueba),** `neblla.shop.purchases['premium']` existe, con `{ type: 'subscription', active: true, renewsAt, trialEndsAt?, cancelAtPeriodEnd }`, y `shop.validate` dice que sí, también desde `room.js`. - **Stripe cobra la renovación solo.** Si un cobro falla, Stripe reintenta durante unos días y el usuario conserva el acceso mientras tanto. - **Cuando termina** (la cancela y acaba el periodo pagado, o los reintentos fallan), deja de contar en todas partes y llega un `shop.on('purchase')` con `type: 'revoked'`, igual que un reembolso. - **El usuario gestiona la suya** con `neblla.shop.manage('premium')`: cancelar, cambiar la tarjeta, facturas. No tienes que montar nada. - **Tus avisos:** el webhook saliente `purchase` llega en el alta y en cada renovación, y `subscription_end` cuando termina (ver core.txt). **Un plan por equipo** (por ejemplo, 9 € al mes por equipo) no es otro tipo de producto: es la suscripción de quien paga más un grupo para su gente (ver identidad.txt, "Grupos y permisos"). Lo montas como quieras; un ejemplo, con tu n8n (o tu servidor) entre los webhooks y la API de administración: ```javascript // 1. Papeles y avisos. Los grupos los crea tu n8n, no el cliente. neblla_update_app({ roles: { titular: { tareas: 'read write' }, equipo: { tareas: 'read write' } }, groups: { invitable: ['equipo'], maxMembers: 10 }, webhooks: [ { event: 'purchase', secret: 'N8N', path: '/equipo-alta' }, { event: 'subscription_end', secret: 'N8N', path: '/equipo-baja' }, ], }) ``` - **Alta.** Llega `purchase` con `{ productId: 'equipo', userId }` (las renovaciones traen `renewal: true` y no tocas nada). Tu n8n crea el grupo y mete dentro al que paga, con `Authorization: Bearer ` (la clave vive en tu n8n, nunca en el cliente): ``` POST https://neblla.com/api/apps//groups/create { "group": "eq-" } POST https://neblla.com/api/apps//groups/add { "group": "eq-", "user": "", "role": "titular" } ``` - **El titular invita a su gente** desde tu app: ```javascript const mio = (await neblla.groups.mine()).find(g => g.role === 'titular'); const { url } = await neblla.groups.invite(mio.group, { role: 'equipo' }); ``` Y el equipo trabaja con filas del grupo: `neblla.db.save(datos, { table: 'tareas', group: mio.group, id })`. - **Baja.** Llega `subscription_end` con `{ productId, userId, reason }`. Tu n8n borra el grupo: `POST …/groups/delete { "group": "eq-" }`. Todos salen; las filas del equipo se quedan, pero nadie llega a ellas desde el cliente. Si vuelve a pagar, el alta crea el grupo con el mismo nombre y recupera esas filas; a su gente la invita otra vez. Otras formas valen igual: quitar solo al equipo y dejar al titular, o pasarlos a un papel de solo lectura (`groups/add` con otro `role`). ## Validación autoritaria `neblla.shop.validate` también se puede llamar desde `room.js` — útil para gatear acciones autoritarias detrás de la posesión de un producto. Ejemplo: para entrar a la sala VIP, `room.js` valida que el usuario tenga `vip_pass` antes de admitirlo, sin que pueda fingirlo desde su cliente. ## Schema de producto Al crear un producto desde el dashboard (o desde el MCP): ```javascript { name: { en: 'Gold skin', es: 'Skin dorado' }, // i18n map o string description: { en: '...', es: '...' }, // opcional image: 'https://.../skin.png', // opcional type: 'one_time' | 'consumable' | 'subscription', price: 499, // unidad más pequeña (céntimos en eur): one_time, o por periodo en subscription interval: 'month', // 'month' | 'year', sólo subscription trialDays: 7, // opcional, sólo subscription pricePerUnit: 10, // unidad más pequeña, sólo consumable step: 1, // tamaño del bundle (consumable) min: 5, max: 1000, // límites del slider (consumable); la compra mínima, 5 × 10, llega al mínimo de Stripe published: true, // visible en shop.products() currency: 'eur', // ISO-4217 (por defecto eur) defaultLang: 'en', // fallback i18n stock: 10, // opcional, one_time y consumable: unidades a la venta en total (null: sin límite) stockRefundReturns: true, // opcional: una unidad reembolsada vuelve a la venta (false en una edición numerada) repeatable: true, // opcional, solo one_time: el mismo jugador puede volver a comprarlo (entradas, regalos). Sin él, un desbloqueo único se compra una vez: la segunda compra se rechaza 409 `already_owned` shipping: { zones: [{ name: 'España', countries: ['ES'], amount: 1500 }] }, // opcional: un producto físico } ``` ## Ficheros a la venta Un **original privado** es un fichero de los medios de la app (`neblla.media`, referencia.txt) que solo descarga quien tiene derecho: «Agua nº 3» en alta resolución, las partituras de una academia en PDF, el pack de texturas HD de un juego, un ebook, un `wav`. De cualquier tipo: imágenes, PDF, EPUB, ZIP, sonido, vídeo. La lectura pública da solo sus variantes hasta el ancho que elige el dev (`publicWidth`, 1280 px por defecto, una vista previa que no se puede imprimir), nunca el original, que vive en un bucket aparte. - **Marcarlo:** `neblla_media` `upload` con `private: true` (y `publicWidth`), o `private` `{ ids | collection, private: true, publicWidth? }` después (Construir › Medios en el panel: «Original privado»). - **Qué lo desbloquea:** `neblla_media` `link` `{ productId, ids | collection }` (y `unlink`): un **producto único** lo desbloquea para siempre (un reembolso completo o una disputa perdida lo retira con la compra); una **suscripción**, mientras está viva (toda la biblioteca de una academia mientras paga). Un consumible no desbloquea ficheros. Y un **tipo de bono** con `unlocks` (core.txt, "Reservas y bonos"): `credits: { descargas: { products: { pack5: 5 }, unlocks: ['agua'] } }`: cada bono desbloquea un fichero de esas colecciones, para siempre («un pack de 5 descargas a elegir de Agua»). - **La descarga:** `neblla.media.download(id, { open? })` **(CLIENT, login)** comprueba la sesión y el derecho y responde `{ url, expiresAt, name, mime, bytes, via }`, un enlace firmado de **5 minutos**, directo del bucket, que se guarda con el nombre del fichero; por defecto empieza la descarga él mismo (`open: false` solo lo devuelve). Cada llamada hace uno nuevo, así que el comprador nunca ve uno caducado, y uno que se pasa a otro deja de funcionar en minutos. Las veces que descarga lo suyo no tienen límite. `neblla.media.unlock(id, kind?)` gasta un bono en un fichero (`{ kind, balance }`, o `already: true` y cómo lo tiene). `neblla.media.mine()` dice qué es suyo: `{ collections: [{ key, via, productId }], items: [{ id, via, productId?, kind? }], content: [{ productId, via, type, label?, url | text }] }` (`content`: el punto siguiente). Un medio privado trae `private: true` y `unlockedBy: { products, credits }` en `neblla.media.collection()`, para enseñar «Comprar» o «Usar una descarga». - **Un enlace o un texto como lo que se compra** (C330): mucho de lo que se vende no es un fichero. Una plantilla de Canva es un enlace («Abrir en Canva»), igual que el vídeo oculto de un curso, una invitación a un Discord o el acceso a una zona de socios; el código de un juego o unas instrucciones son un texto corto. Un producto único o una suscripción lleva, además de sus ficheros, **contenido privado**: `neblla_create_product` / `neblla_update_product` con `content: [{ type: 'link', label: 'Abrir en Canva', url }, { type: 'text', label?: 'Tu código', text }]` (`label` un texto o uno por idioma `{ es, en }`; hasta 10 piezas; `content: null` lo quita; un consumible no lo lleva), o en el panel, al editar el producto, «Lo que recibe el comprador». El catálogo público nunca lo da: `neblla.media.mine()` se lo da a quien tiene el producto, en `content: [{ productId, via, type, label?, url | text }]`, con la misma regla que los ficheros (la compra única para siempre, la suscripción mientras está viva, la compra sin registrarse, C94, como cualquier otra), para que la app pinte «Abrir en Canva» al lado de «Descargar». La ficha del comprador en el panel enseña qué le da cada compra. Son datos de la app: una fila de su almacén (la base de datos del dev con BYODB). Sé honesto con el comprador: Neblla decide quién ve el enlace, no puede impedir que lo reenvíe (un enlace que no debe viajar es un fichero, o un enlace del propio servicio que le pide entrar). - **Quién lo tiene:** `neblla_media` `holders` `{ id }` (el panel, «Quién lo tiene»): cada uno con su email, cómo (compra, suscripción, bono) y desde cuándo. `download_link` `{ id }` da al dev su propio enlace. - Errores: `login_required`, `not_entitled` (lleva `unlockedBy`), `not_private`, `no_credits_unlock_it`, `kind_required` (lleva `kinds`), `kind_does_not_unlock`, `not_enough_credits`, `media_private_storage_off` (este Neblla aún no tiene bucket privado). ## Unidades a la venta Un producto único o un consumible puede tener **N unidades a la venta** (`stock`): una edición de 10 copias, 100 espadas legendarias, 50 tazas, entradas sin butaca. `neblla.shop.products()` dice, de cada uno con stock, `stock: { units, left, soldOut }` («quedan 7 de 10», «agotado»), nunca quién está pagando ni quién compró. Abrir el pago **aparta** las unidades compradas mientras vive el checkout (se cierra a los 30 minutos más o menos, en vez de las 24 horas de Stripe): pagadas, se venden; abandonado, vuelven solas; con un reembolso completo, vuelven a la venta salvo `stockRefundReturns: false` (una edición numerada y firmada). Sin unidades, `shop.buy` rechaza con `sold_out` (y `left`); dos compradores a la vez nunca se llevan la última los dos. El dev pone y cambia las unidades con `neblla_create_product` / `neblla_update_product` (`stock`, `stockRefundReturns`) o en Dinero › Productos, donde cada producto enseña lo que queda, lo que se está pagando y lo vendido; bajarlas por debajo de lo vendido deja cero. Una compra de prueba en el pre se rechaza si no queda ninguna, pero no aparta ni vende: las unidades son de pro. Un **desbloqueo único** (`one_time` sin `tokens`) se compra una vez por jugador: si ya lo tiene (un móvil que perdió su copia, una segunda pestaña), `shop.buy` rechaza con `already_owned` y `getPurchases()` se refresca con lo que dice el servidor, para que la app muestre «ya lo tienes» en vez de cobrar dos veces. Los paquetes de fichas, los consumibles, las donaciones y las suscripciones tienen sus propias reglas y nunca contestan `already_owned`. Las entradas y los regalos, que sí se compran otra vez, llevan `repeatable: true` (`neblla_create_product` / `neblla_update_product`, o el interruptor «Se puede volver a comprar» en Dinero › Productos). Un desbloqueo reembolsado se puede volver a comprar. ## Donaciones (importe libre) Un producto `donation` es lo que da quien quiere dar, y no entrega nada a cambio: la taza de «Invítame a un café». Quien dona **elige el importe en la página de Stripe** (con el botón «Donar», en su idioma y con una línea de agradecimiento), así que no tiene `price`, `pricePerUnit`, `min`/`max`/`step`, `stock`, `shipping`, `seller` ni suscripción: solo `minAmount` (lo menos que se puede dar, en la unidad más pequeña de la moneda; por defecto 100 = 1 €), `maxAmount` (por defecto 50000 = 500 €) y `presetAmount` (el que Stripe ofrece primero; por defecto 300 = 3 €). `neblla_create_product({ appId, productId: 'cafe', name: 'Invítame a un café ☕', type: 'donation' })`; cambiar los límites o el nombre hace una página de Stripe nueva sin tocar nada más. **Una donación no pide Login:** `neblla.shop.buy('cafe')` funciona sin sesión y la donación es anónima (sin persona ni cliente de Stripe; el email y el recibo los gestiona Stripe en su página, y Neblla no guarda el email ni la IP). Con Login, la donación es del donante (persona, cliente, recibo a su email). Vale también con `purchases.emailCheckout: false`. Para frenar a quien prueba tarjetas, hay un límite por IP y por app: pasado, `buy()` falla con `too_many_requests` y `retryAfter` (segundos). Ventas muestra «Donación · anónima» y los webhooks `purchase`/`refund` llevan `anonymous: true` y `userId: null`. Mientras tu cuenta de Stripe no esté activa el producto espera (`product_waiting` / `payouts_not_ready`), como los demás. - **Sin comisión:** con el importe libre Neblla no puede fijar su 1 % de antemano y Stripe no tiene porcentaje para un pago suelto: una donación no paga comisión a Neblla. Solo la de Stripe, que va a tu cuenta. - **Lo que se registra:** el importe **real** (`paid`, con el impuesto que Stripe Tax haya añadido, y `amountNet`, sin él, el que ves en Dinero › Ventas con la etiqueta «Donación»). Sin tope superior en el servidor: lo pone la página de Stripe con `maxAmount`. Un pago por debajo de `minAmount` no se registra y avisa. - **El evento `purchase`** llega a los dispositivos de quien donó con `productType: 'donation'`, `donation: true`, `paid` y `currency`, para decir «¡Gracias!». No entrega nada, no cuenta en `purchases` y `shop.consume`/`validate` no se aplican. - **Reembolso:** el de siempre desde Dinero › Ventas (entero, sin comisión de Neblla que devolver). ### La firma: logo de Neblla y taza de café `neblla_update_app({ signature: { enabled: true, position: 'top-left' } })` (o el combo «Firma y café» en Dinero › Productos › Tienda) dibuja arriba el logo de Neblla y una taza; la taza abre un panel con «Invitar», que lleva al pago de Stripe con el importe libre. Al encenderla se crea sola la donación `cafe` (nombre «Invítame a un café ☕», sugerido 3 €, mínimo 1 €) y espera a la cuenta de cobros. «Invitar» no pide Login (la donación es anónima si no hay sesión). Sin código propio: pon `` donde la quieras, o `neblla.signature.mount(el)`. Con el módulo `shop` apagado solo sale el logo. Es un ajuste del dueño: las copias de un ejemplo nacen sin firma. Pasa por «Pasar a pro» como el resto de ajustes. ## Productos físicos y pedidos Un producto único o un consumible con `shipping` es **físico**: copias impresas de una foto, tazas, camisetas, un fanzine impreso. `shipping: { zones: [{ name, countries, amount }] }`: cada zona con sus países (códigos ISO, un país en una sola zona) y sus gastos de envío en la moneda del producto (0: gratis), p. ej. «España 15 €, resto de Europa 35 €». - **El checkout** pide la dirección en los países de UNA zona y cobra su envío: la elige el país del comprador, `neblla.shop.buy(productId, amount, { country: 'ES' })`, o la única zona que haya. Con varias zonas y sin país, `shop.buy` rechaza con `country_required` y `zones` (`[{ name, countries, amount }]`): pregunta al comprador adónde va (el catálogo ya trae `shipping.zones` para enseñar el envío) y vuelve a llamar con el país; un país fuera de ellas, `country_not_shipped`. Así el envío pagado siempre casa con la dirección. - **Cada pago es un pedido** (Dinero › Ventas, encima de las ventas; `neblla_orders`): la dirección (nombre, teléfono, dirección), la zona y el envío, y un estado: `paid` → `shipped` (con `carrier`, `tracking` y su `trackingUrl`) → `delivered`, o `returned`. Un reembolso completo lo marca `refunded`: no lo envíes. `neblla_orders` `update` `{ orderId, status?, carrier?, tracking?, trackingUrl? }` lo hace avanzar (enviado pide transportista o número de seguimiento; un paso atrás corrige un error). - **El comprador se entera de cada paso** en su buzón (`neblla.inbox`, con el módulo inbox encendido), en su idioma y con el seguimiento: «¡Hola, Marta! Tu pedido de «Agua nº 3» ha salido. Transportista: Correos. Seguimiento: PK123ES.», con `data: { type: 'order.shipped', order, status, carrier, tracking, trackingUrl }` para que la app lo pinte a su manera. `neblla.shop.orders()` le da sus pedidos. - **Los 14 días de desistimiento de la UE** cuentan desde la entrega: cada pedido entregado trae `withdrawal: { until, open, daysLeft }`, y el aviso de entrega le dice al comprador hasta cuándo. - No es de Neblla, a propósito: etiquetas de transportista, almacenes, devoluciones con logística y carritos de muchos artículos. La tienda que los necesita crece hacia Shopify; dilo cuando salga. ## Impuestos El vendedor eres tú (el cobro se hace en tu cuenta de Stripe), así que los impuestos son tuyos. Puedes configurar Stripe Tax en tu propio panel de Stripe, o dejar que Neblla te lo monte con `neblla_tax`: - `status` dice si los ajustes están activos y qué falta; `set_head_office` pone la dirección de tu negocio; `set_defaults`, el código fiscal por defecto (`txcd_…`) y cómo se aplica el impuesto. - `add_registration` / `expire_registration`: los territorios donde estás dado de alta para cobrar impuestos. Sin alta en el sitio del comprador, no se cobra impuesto ahí. Darte de alta ante Hacienda es un paso legal tuyo; aquí solo se le dice a Stripe. - `report`: el detalle de transacciones con impuestos para un periodo, con un enlace de descarga temporal. Los informes de impuestos también están en tu panel de Stripe. - `app` con `{ appId, automatic: true }`: el checkout de esa app calcula el impuesto mientras tus ajustes estén activos. **Por defecto el precio ya lo incluye,** como espera un consumidor europeo; con `{ inclusive: false }` se suma encima, lo habitual al vender a empresas o en EE. UU. La comisión del 1 % sigue calculándose antes de impuestos. ## Tu cuenta de cobros Para vender necesitas una cuenta de Stripe conectada a Neblla. Se abre la primera vez que pides el alta (`neblla_payments_account` con `onboarding_link`, o "Configurar Stripe" en tu cuenta del panel), no al registrarte. El alta es la de Stripe, dentro de neblla.com: el formulario de Stripe aparece en tu cuenta del panel, con tu email, tu nombre y la web de tu studio (`play.neblla.com/studio/`, ver publicar.txt) ya rellenados. La cuenta es tuya y vale para todas tus apps: el alta no va atada a ninguna. Un proyecto puede vender con un Stripe propio (`neblla_projects` con `use_own_stripe`; `neblla_payments_account` y `neblla_tax` con su `projectId` actúan sobre esa cuenta) y los demás usan el de la cuenta. Una app que vende (productos de pago o suscripciones vivas) no puede moverse a un proyecto con otro Stripe: lo vendido sigue atado a la cuenta en la que se vendió. Identidad, cuenta bancaria y tu usuario de Stripe van directamente a Stripe; Neblla nunca los ve ni los guarda, y el MCP nunca te los pide. Si ya usas Stripe, entra con tu usuario durante el alta y la cuenta nueva queda junto a las que ya tienes. Si publicas un producto de pago antes de tenerla, no hace falta ir a buscarla: el panel te lleva al alta en ese momento, y por el MCP la respuesta trae `connectRequired: true` y `connectUrl`, una página de neblla.com que abre el alta desde tu sesión (el enlace de Stripe en sí no sale de Neblla). El producto queda guardado, oculto a los usuarios y esperando (`publishWhenReady`), y se publica solo en cuanto Stripe da la cuenta por activa. **Qué falta, en palabras.** `neblla_payments_account` con `status` (o Ajustes › Cuenta › Stripe) le pregunta a Stripe cada vez y dice qué falta agrupado por cosa, no por campo: «Faltan 3 cosas: tu cuenta bancaria (IBAN), tu fecha de nacimiento y aceptar las condiciones de Stripe; tu email, tu nombre y tu web ya están». `missing` trae `{ key, words, overdue }`; `errors`, lo que Stripe no pudo verificar; `verifying`, lo que está comprobando; `filledByNeblla`, lo que rellenó Neblla; y `disabledReason` si Stripe paró la cuenta. Eso solo lo puedes poner tú, en el formulario de Stripe: al volver de él, vuelve a pedir `status` y verás lo que queda. Si Stripe no responde, `status` dice `stripeReachable: false` con el porqué (`error.kind: down`), y no te dice «pendiente». Si la cuenta guardada no existe en la plataforma de Neblla (por ejemplo, se abrió con la clave de prueba de Stripe), lo dice (`lostAccount.reason`: `test_mode_account`, `live_mode_account` o `not_on_platform`) y el siguiente alta abre una nueva; si vuelve a estar a mano, se recupera sola. **Lo que pone el extracto del banco.** En un cobro con tarjeta el extracto de tu cliente dice tu studio y la app, 22 letras como mucho: «GRACIA* AJEDREZ». El prefijo (2 a 10 letras latinas o números, con al menos una letra) es de tu cuenta: Neblla te propone el nombre corto de tu studio al hacer el alta y lo cambias con `neblla_payments_account({ action: 'set_descriptor', prefix: 'GRACIA' })` o en Ajustes › Cuenta › Stripe. El sufijo es la app, cortado para que quepa; vale para compras sueltas y pagos al reservar. En una suscripción Stripe pone la línea entera sin asterisco («GRACIA AJEDREZ»). El recibo de Stripe nombra la app: «Ajedrez · Pase del club». La cuenta es tuya, con el panel completo de Stripe (pagos, transferencias, reembolsos, disputas, impuestos); `dashboard_link` te lleva a él. Como el cobro se hace en tu cuenta, la comisión de Stripe, los reembolsos y las disputas van por tu cuenta, y si tu saldo queda en negativo es Stripe quien te lo reclama, no Neblla. Puedes desconectar Neblla cuando quieras, desde Neblla (la cuenta queda guardada para volver a ella) o desde tu panel de Stripe (Neblla deja de vender por ti en ese momento). ## Varios vendedores, cada uno cobra lo suyo Una app con muchos vendedores — los clubes de una app de pádel, las artistas de una galería, los autores de una tienda de plantillas, los profes de una plataforma de clases — cobra cada venta **en la cuenta de Stripe del vendedor**, no en la tuya. Tú te quedas tu comisión y Neblla la suya de siempre. Vale igual para juegos, apps y webs. - **El vendedor.** Una sede de tu negocio (`site:`: la que sale de una solicitud aprobada con `neblla.business.apply`, o una que creas tú) o un usuario de la app que tú marcas (`user:`): `neblla_business` con `addSeller { seller, name? }`. Su cuenta es del mismo tipo que la tuya (el panel completo de Stripe, a su nombre); nunca Express. - **El alta.** La hace el vendedor, con sus datos, en el formulario de Stripe. Desde la app: `neblla.business.sellers.mine()` lista los vendedores de los que responde el usuario (él mismo, si lo marcaste; las sedes de sus solicitudes) y `neblla.business.sellers.connect({ seller })` devuelve `{ url }`, que la app abre en el momento (un solo uso, unos minutos). Desde el backoffice, el equipo de una sede (C350) lo pide con `sellerLink` para la suya; tú, con `neblla_business({ action: 'sellerLink', seller })`. Al volver, Stripe le deja en una página de Neblla que le dice si ya puede cobrar. `sellers` te enseña el estado de cada uno (`not_connected`, `pending`, `restricted`, `active`, y lo que falta). - **Qué vende cada uno.** Un producto lleva `seller` (`neblla_create_product({ …, seller: 'user:' })`): un pago único, un consumible o una suscripción. Un servicio pagado al reservar dice `seller: 'site'` en su set (`neblla_update_app({ business: { booking: { pistas: { product: 'pista', seller: 'site' } } } })`): cada sesión se cobra en la sede donde es — la pista de Club Norte, en la cuenta de Club Norte —; o un vendedor fijo (`seller: 'site:club-norte'`). Las plazas fijas son productos: llevan su `seller`. En la app, `neblla.business.booking.services()` dice en ese servicio `seller` y `sellerWaiting`, los vendedores que aún no cobran (`['site:club-norte']`): sus sesiones contestan `seller_waiting` al reservar, así que la app puede avisar antes («Este club aún no cobra por la app»). - **Tu comisión.** `neblla_update_app({ business: { sellers: { fee: { percent: 10, fixed: 50 } } } })`: un porcentaje (hasta el 50 %, con dos decimales) y/o un fijo en céntimos por venta; en una suscripción, el fijo se convierte en porcentaje de su precio. Va junto a la de Neblla en la comisión de aplicación del cargo, y te llega a tu cuenta de cobros cuando Stripe la deja disponible en el saldo de Neblla (unos días): Neblla nunca la adelanta. Con comisión, necesitas tu cuenta de cobros activa (`payouts_not_ready`). Nunca puede quedarse con todo el pago (`seller_fee_too_high`). - **Quién carga con qué.** Como el cobro se hace en la cuenta del vendedor, la comisión de Stripe, los reembolsos y las disputas son del vendedor, y si su saldo queda en negativo es Stripe quien se lo reclama, no tú ni Neblla. Cuando Neblla devuelve una venta (Dinero › Ventas, una reserva cancelada a tiempo), la devuelve el vendedor; la comisión de Neblla vuelve al vendedor, y la tuya también si aún no te la pagó o si se puede revertir; si tu saldo no la cubre, la carga el vendedor. Un reembolso que hace el vendedor en su Stripe, o una disputa, no devuelve comisiones: lo carga el vendedor, como dice Stripe. - **Mientras no está lista.** Lo de un vendedor sin cuenta activa espera: `shop.products()` lo marca `waiting` y comprar o reservar falla con `seller_waiting` (con `seller` y `status`). Las apps de ejemplo venden en modo prueba también para sus vendedores (cada uno con su cuenta de prueba). - **Ventas.** Cada venta dice `seller` y `sellerName`; `neblla_sales list { seller }` (o Dinero › Ventas) filtra por vendedor, y el equipo de una sede solo ve las de su sede. - **Lo que no está.** La reventa entre usuarios (un jugador que vende a otro lo que compró). Un bono de una sede vale en todas: los créditos son de la app (para limitarlo, un tipo de crédito y un servicio por sede). Los traspasos de tu comisión solo cruzan fronteras entre EE. UU., Canadá, Reino Unido, el EEE y Suiza. ## Fichas: el saldo propio de la app Una app puede tener **su propio saldo** (fichas, diamantes, tickets, monedas de un festival): el jugador lo **compra en packs** con Stripe y lo **gasta dentro**. Se enciende con el módulo `tokens` (opt-in, depende de `shop` y `auth`; no con BYODB: `tokens_need_neblla_db`). El nombre lo pone la app (`kinds.default.name { one, many }`). **Neblla no guarda ni mueve el dinero:** el pago de cada pack lo recibe la cuenta de Stripe del organizador, que es quien devuelve y quien paga a los vendedores; Neblla solo lleva la cuenta. - **Un pack** es un producto `one_time` o `consumable` con `tokens: N` (fichas por unidad; `neblla_create_product({ …, tokens })`, o «Da N fichas» en Dinero › Productos). No en suscripción ni donación, ni en un producto que ya da créditos de negocio o paga una reserva. Todos los packs van en la misma moneda (`tokens_one_currency`). - **Cada compra es un lote** con su caducidad (la configuración del momento de comprar) y su neto (lo cobrado menos las comisiones de Stripe, de Neblla y del organizador). Se gasta en orden (FIFO). Los créditos de los bonos de negocio (`business.credits`) son lotes del mismo motor: `neblla.business.credits.*` sigue funcionando. - **El suelo** es lo que vale una ficha al pagar a los vendedores: Neblla sugiere el valor del pack más barato tras comisiones y el organizador lo confirma (`floor`). Lo que una ficha vale de más es **excedente** del organizador (puede ser negativo: se ve). - **Aviso antes de pagar:** `neblla.tokens.buy(productId)` enseña una hoja (en los 10 idiomas, lee ``) con las fichas, quién cobra, que las comisiones de terceros no se devuelven y la caducidad; si la app dibuja la suya, `buy(id, { noticeShown: true })`. - **Devoluciones:** si el organizador las abre (`refunds.open`), `requestRefund()` devuelve **el neto de las fichas sin usar** de cada lote desde su Stripe (reembolso parcial); las comisiones ya cobradas no se recuperan. Errores: `refunds_closed`, `nothing_to_refund`, `too_old_to_refund`. - **Disputas:** una abierta **congela** el lote; ganada lo descongela, perdida lo anula. Tres disputas no ganadas de una persona bloquean sus pagos en todo Neblla (`payments_blocked`). ### SDK del jugador (`neblla.tokens`, con `tokens` encendido) ```js const info = await neblla.tokens.info(); // { name:{one,many}, packs:[{productId,tokens,price,currency}], paused, refundsOpen, expiry, organizer } await neblla.tokens.buy(info.packs[0].productId); // abre la hoja y Stripe; rechaza con 'cancelled' si dice que no const { tokens, frozen, expired } = await neblla.tokens.balance(); const items = await neblla.tokens.items(); // [{ itemId, name, price, vendorId, vendor }] const r = await neblla.tokens.spend({ itemId, qty: 1 }); // { spendId, code, tokens, balance }; la `key` la pone el SDK y reintenta con la misma neblla.tokens.on('tokens', (b) => {}); // el saldo cambia (compra, gasto, caducidad, devolución) await neblla.tokens.history(); await neblla.tokens.requestRefund(); ``` Errores con `code`: `login_required`, `not_enough_tokens` (alias `not_enough_credits` en los bonos), `tokens_paused`, `tokens_expired` (pasó la fecha de caducidad: no se vende ningún pack), `item_inactive`, `refunds_closed`, `payments_blocked`. ### Servidor (room.js y API) - `room.js` (peer servidor de una sala real): `neblla.tokens.spend(userId, { itemId | tokens, key })`, `neblla.tokens.balance(userId)`, `neblla.tokens.gift(userId, n, { key })`. La **`key` es obligatoria** en lo que cambia saldo: todos los Fog que corren `room.js` piden con la misma y el efecto ocurre una vez. - HTTP con la clave de servidor: `POST /api/apps//tokens/` `{ userId, key, itemId? | tokens?, qty?, kind?, reason? }`. - MCP: `neblla_tokens_read` / `neblla_tokens` (configuración, saldo, informe, cortes, anular un gasto). Regalar fichas es del panel (aprueba dinero). ### Informe del organizador Dinero › **Fichas** (ajustes y avisos) y **Informe de fichas**: neto cobrado, vendidas, regaladas, gastadas, vivas, caducadas, congeladas, excedente, pérdidas por disputa y dinero **libre de disputa** (compras de más de 120 días sin disputa, o de antes de `eventDate`: una referencia, no una garantía de Stripe). Cortes guardados («Viernes noche») y CSV. ## Vendedores (puestos) y su cuenta Un **vendedor** es un puesto o tienda que vende **sus** productos dentro de la app (la barra 1 de un festival, la cantina de un torneo). Módulo `vendors` (opt-in; el módulo `tokens` lo incluye): feature **independiente** de las fichas. Un producto de un vendedor se paga **con tarjeta** (`priceCents`, un carrito con productos de varios puestos es **un solo cobro** en la Stripe del organizador) o **con fichas** (`price`) o con las dos. Neblla lleva la **cuenta**: lo que vendió cada puesto, lo que se le debe (con tarjeta, al precio de venta; con fichas, al suelo) y lo pagado. **Neblla no guarda ni paga ese dinero:** lo cobra el organizador y paga él; lo registra en Neblla y el vendedor lo **confirma** (o dice «no recibido»). - **Carrito con tarjeta:** `neblla.cart([{ itemId, qty }], { lang? })` (junto a `neblla.buy`, dentro del clic) → `{ cartId, total, currency }`. Los precios son los de Neblla. Errores: `item_not_found`, `item_inactive`, `item_not_for_card`, `cart_one_currency`, `invalid_cart`, `login_required`, `payments_blocked`, `payouts_not_ready`, `popup_blocked`. - **Saber que se pagó (carrito con tarjeta):** `neblla.cart(lines, { wait: true })` resuelve `{ paid: true, cartId, lines, total, currency }` al pagarse (o `{ paid: false, status: 'refunded' }` si acabó devuelto) y rechaza `timeout` a los 10 min (no sabemos si pagó: pregunta con `neblla.cartStatus`). `neblla.cartStatus(cartId)` → `{ status: 'open'|'paid'|'refunded'|'partial', lines, total }` (solo tu carrito). El evento `neblla.shop.on('cartPaid', fn)` llega al comprador en todos sus dispositivos (retenido si el móvil estaba en reposo) y a la gente de cada puesto **solo con sus líneas y su total**. Con la pestaña oculta no se sondea; al volver se pregunta una vez. - **¿Fichas o tarjeta?** Carrito con **tarjeta** → `cart` + `cartPaid`/`wait`. Pedido con **fichas** (Cola) → `neblla.tokens.spendOrder`, que ya devuelve el resultado y el número. Son dos pagos distintos; no se mezclan. - **Con fichas:** `neblla.tokens.items({ vendorId })` y `neblla.tokens.spend({ itemId })`; cada cobro lleva un **código corto** para que el puesto lo reconozca. - **La ficha del puesto** (Dinero › Vendedores): debe cobrar, pagado confirmado, registrado sin confirmar, unidades, ventas con tarjeta y con fichas, ventas en vivo con su código, pagos con su estado. La ven la dueña y el puesto, **la misma pantalla**; el puesto solo ve la suya. - **Equipo:** el grupo **«Puesto»** (`own: true`, la pertenencia lleva `vendorId`) entra directo a su ficha, sin el resto del panel; no ve otro puesto ni el informe. Solo el puesto confirma o rechaza un pago. - **Avisos:** el puesto lee en su ficha y en el correo de invitación (10 idiomas) que Neblla no guarda ni paga ese dinero. - **MCP propio:** `neblla_vendors_read` (`vendors`, `items`, `sheet`, `payouts`) y `neblla_vendors` (`createVendor`, `updateVendor`, `createItem` con `priceCents` y/o `price`, `updateItem`, `deleteItem`, `registerPayout`). Funciona con el módulo `vendors` o con `tokens`. ## Cola: turnos y pedidos de un puesto Módulo `queue` (opt-in; necesita `vendors` y `auth`). Cada vendedor (puesto) tiene **una cola**: el cliente paga o pide, **Neblla le da un número** y el puesto lo atiende en orden. Sirve para una feria con varios puestos, una carnicería con un solo puesto o un cine con una cola por sesión. Cada app pone su pantalla: la cola va por debajo, en `neblla.queue`. - **Quién manda:** el móvil del **jefe** del puesto lleva la fila, los estados y la hora estimada; si se va, manda el primer **suplente** presente (orden de herencia), y al volver el jefe recupera. Un **empleado** pide «¿cuál es el siguiente?» y un **punto** (una tablet) solo saca números o teclea códigos de talonario. Los clientes hablan con el jefe **cifrados** por el relé de Neblla, que lleva los bytes y no los puede leer. - **El número lo da Neblla** (un contador por puesto y día, una sola vez por venta): no se duplica ni aunque el jefe cambie de móvil. Un cliente sin autoridad conectada ya tiene su número; el jefe lo ve al volver. - **Cliente:** `neblla.queue.queues()`, `take(vendorId, { saleRef })` (tras `neblla.tokens.spend` o `spendOrder`; en una cola sin pago, sin `saleRef`), `mine()`, `watch(vendorId)`, `status`, `answer(vendorId, number, option)` (cuando algo se agota), `remake(vendorId, { saleRef, lines })` (rehacer el pedido sin perder el turno), `leave`. Eventos: `neblla.queue.on('queue', …)` con estado, posición, hora estimada y agotado. - **Personal:** `staff()` (los roles de quien hizo Login), `run(vendorId)` → `next()`, `setState(n, estado)`, `callBatch`, `soldOut(itemId, { fromNumber | left })`, `close({ mode: 'new' | 'all', at })`, `invite({ email, role })`, `setOrder(emails)`, `walkIn({ name })` (a nombre de alguien sin móvil), `ticket('B3')` (talonario en papel en el punto), `refund`, `markServed`. Estados: esperando, avisado, de camino, llamado, en preparación, listo, atendido, movido, cancelado. - **Invitar:** Ana invita al jefe desde Dinero › Vendedores (o `neblla_vendors` con `queueInvite`): el enlace lleva a **la app**, la persona hace Login con ese email y acepta; no necesita cuenta de developer. Una app sin email en el Login no puede invitar. - **El número viaja con el pago (OP-1):** con la cola del puesto abierta, `neblla.tokens.spendOrder` y `neblla.queue.spendFor` devuelven en cada pedido `queue: { number, day, epoch, queueAt }` (o `queue: { error }` si la cola se cerró justo entonces: el cobro NO falla, se repara con `take(vendorId, { saleRef })`). El SDK ya lo apunta en `mine()` y lo presenta a la cola: no hace falta llamar a `take` tras pagar. Si la respuesta del pago se pierde (`timeout`), el SDK guarda la marca y, al volver, pregunta con una lectura (`lookupSpend`, nunca paga de nuevo): si se cobró, dispara `neblla.tokens.on('orderRecovered', ({ orders }) => …)` con el pedido y su número; si no, descarta la marca. `neblla.tokens.history()` pone `saleRef` y `queueNumber` en cada gasto de un puesto: los que traen `queueNumber: null` se reparan con `take(vendorId, { saleRef })`. **«Tomar el mando»:** `neblla.queue.takeCommand(vendorId)` (jefe o suplente de menor orden) recupera el mando de la línea (hace falta un canal P2P abierto). - **Dinero:** una devolución de fichas sale de la cola (agotado, desmantelado, cierre) pero **nunca de un pedido ya entregado**; un pedido con tarjeta pide el reembolso a Ana (filtro «Devolución pedida» en Ventas). Las fichas de un pedido con varias líneas: `neblla.tokens.spendOrder({ lines })` (un gasto, una venta por línea, un número por puesto). Pon en cada línea el `price` que enseñaste (o `expect` con el total de un carrito de un puesto): si el precio cambió, no cobra y devuelve `price_changed` con `expected` y `tokens`. - **Cerrar:** «cerrar a nuevos» y luego cierre completo; lo que quede se trata como un pedido desmantelado. - **Límites:** solo en línea (sin Bluetooth ni modo sin conexión), sin aviso al móvil con la app cerrada, un evento grande pide Atlas y Render de pago (ningún merge a producción durante el evento). - **MCP:** `neblla_vendors_read` con `queue` (opciones y personal con sus invitaciones) y `neblla_vendors` con `queueInvite`, `queueRevoke` y `queueOrder`. Ejemplo completo: «Feria del Barrio». ## Estaciones de una cola (cocina por puestos de trabajo) Una cola puede repartir el trabajo de un puesto en **estaciones** (parrilla, freidora, barra). Tres niveles, sin cambiar la API de cola: **0 estaciones** es la cola de siempre (turnos y estados a mano); **1 estación** con capacidad solo mejora la **hora estimada**; **2 o más** reparten cada pedido en **comandas** por estación y el motor deriva el estado del pedido (esperando, en preparación, listo). Con 2 o más estaciones `setState` a mano da `queue_kitchen_derived`. - **Configurar:** el jefe, o la autoridad que manda ahora, con `neblla.queue.setStations(vendorId, { stations: [{ id, name, capacity }], itemStation: { itemId: stationId }, itemSlots: { itemId: huecos }, atDelivery: [itemId], pass, parts })` y `neblla.queue.stations(vendorId)`; Panel › Cola › Estaciones; MCP `neblla_vendors` `queue` con `stations`. La estación vive en la cola, no en el producto ni en el catálogo público. Cruzar el umbral de 2 estaciones con la cola abierta da `queue_stations_live`; un suplente que no manda recibe `not_allowed`. Una estación borrada deja sus productos «sin decidir» con aviso, nunca «al entregar» por omisión. - **La capacidad no bloquea:** son pedidos/huecos que la cocina hace a la vez; solo alimenta la hora. Un solo toque obligatorio: **«hecho»**. - **Personal:** `neblla.queue.watchStations(vendorId, ids | '*')` (la pantalla de una estación: `board`, sus líneas), `start`, `done(vendorId, ref, { qty, opId })`, `undo` (8 s) y `redo`, `confirm`, `deliver` y `bagClosed` (nunca desde una pantalla `fixed`, la tablet a la vista del público), `closeStation(vendorId, id, on)`, `soldOut(vendorId, itemId, { left, fromNumber, until })` por línea («el resto sigue» si nadie contesta), `note` y `setItems` (pedido sin pago, como «Mesa 12»). Cada toque lleva `opId`: un reintento no avanza dos estados. - **La hora:** `stationPlan` junta pedidos que arrancan a la vez (ventana `JOIN_WINDOW` de 90 s) y da un **rango** con aviso de retraso. La autoridad publica `queueStatus` (1/s por puesto, público): `neblla.queue.statusOf(vendorId)` y `neblla.queue.quote(vendorId, lines)` dan la hora **antes de pagar**, calculada en el cliente sin preguntar a nadie. - **Cliente:** ve su rango, lo que tiene delante y sus partes (`parts`); **nunca la cocina** (estaciones, notas de otros, líneas ajenas). Un solo aviso de «listo» cuando están todas las comandas (8 s después del último «hecho»). - **Devoluciones por partes:** `refund { line: saleId, qty }` solo de esa fila, sin devolver dos veces lo mismo (`returned` por lote); `markServed({ lines })` marca por fila; una fila entregada no se devuelve. - **Privacidad y recuperación:** el personal se identifica por **id y etiqueta**, nunca por email; la pantalla de estación ve **las líneas de su estación** de cada pedido. La autoridad guarda en su móvil una copia sellada (`v: 2`, versiones desconocidas rechazadas) que se borra al cerrar la cola y a las 24 h; sin copia, lo que se estaba haciendo vuelve «por confirmar» y ocupa hueco. - **Límites:** las pantallas de estación son tráfico del relé (cuota de la app, ≤ 10 sobres/s sostenidos); ni impresoras, ni modo por tandas, ni dos estaciones iguales con reparto (ideas para después). Ejemplo completo: «Feria del Barrio». ## Comisión Neblla se lleva el **1 % de cada venta, antes de impuestos**. La comisión de Stripe va aparte y la paga tu cuenta de Stripe, porque el cobro se hace en ella: tú eres el vendedor. No hay cuota fija por venta ni por producto. ## Garantías Los pagos están mediados: `room.js` solo ve el resultado (la compra confirmada), nunca datos de tarjeta, ni tiene capacidad de regalar ítems gratis o falsificar compras de otro usuario. Un gasto se hace entero o no se hace: pedir gastar más unidades de las que tiene el usuario no le quita nada, en lugar de vaciar lo que había y fallar después. ## Una tienda de un vendedor, de punta a punta Este es el recorrido completo de un pedido, porque las piezas están repartidas por tres capítulos y por separado no se ve que el circuito cierra. El caso es **tú vendes a tus usuarios** — un MVP tipo Etsy con un solo vendedor, que eres tú. Si los que venden son varios (clubes, artistas, autores), mira "Varios vendedores, cada uno cobra lo suyo", arriba; lo que no existe es la reventa entre usuarios. **0. Cobrar de verdad.** `neblla_payments_account` conecta tu Stripe Connect. Hasta que esté activa, todo producto queda con `published: false` por la fuerza — o sea que puedes montar el catálogo entero antes de tener papeles, pero nadie podrá comprar. **1. El catálogo.** `neblla_create_product` con `price` en **la unidad más pequeña de la moneda** y `currency` ISO 4217 (por defecto `eur`; cualquiera que cobre Stripe). El precio va en la unidad más pequeña de la moneda: céntimos en casi todas, unidades enteras en las que no tienen (`jpy`, `krw`…), milésimas acabadas en 0 en `bhd`, `jod`, `kwd`, `omr` y `tnd`. Lo que Stripe no cobraría se rechaza al crear o editar el producto con `invalid_price`, no al pagar: una moneda que no acepta, o un precio bajo su mínimo (0,50 € o 0,50 $; en un consumible, la compra mínima, `min` × `pricePerUnit`). Si el usuario dio su email a la app, Stripe le manda el recibo. `name` y `description` aceptan un objeto por idioma. Dos tipos y no son intercambiables: `one_time` para la pieza única que se vende una vez, y `consumable` con `min`, `max` y `step`, que es literalmente un selector de cantidad. El cliente pinta la tienda con `neblla.shop.products()`. **2. Las fotos van por URL, y una de esas URLs puede ser de Neblla.** `image` es una **URL**, no un fichero subido al producto. Pero no te vayas a buscar un CDN por un JPEG de 40 kB: **sube la foto como fichero de la app** —`neblla_upload_file` acepta binarios hasta 25 MB— y pasa su URL pública. Una app publicada la sirve desde Cloudflare sin gastar cuota; en pre o en una app en caliente cuenta sus bytes, salvo cuando el navegador ya la tiene. Lo que gastas es el cupo de ficheros (300 por cuenta gratis, compartidos por sus apps, o 600 por proyecto Pro, compartido con el HTML, el CSS y todo lo demás); para un catálogo grande, guarda las fotos en tu propio almacenamiento y enlázalas. No las metas en base64 dentro de otro sitio para esquivarlo: ahí las pagas en cuota cada vez que alguien abre la tienda. **3. El pago.** `neblla.shop.buy(productId, amount)` abre una ventana de checkout de Stripe de verdad; la promesa resuelve cuando la ventana está abierta, y la compra confirmada llega después por `neblla.shop.on('purchase')`. Después, `neblla.shop.purchases` lo lleva, salta `neblla.shop.on('purchase')`, y el servidor revalida contra Stripe por su cuenta — lo que un cliente afirme sobre lo que compró no es la autoridad. **4. El pedido.** Para algo que se envía, dale al producto `shipping` ("Productos físicos y pedidos", arriba): el checkout pide la dirección y cobra el envío de la zona del comprador, cada pago es un pedido con su estado en Dinero › Ventas y `neblla_orders`, y el comprador se entera de cada paso en su buzón. Lo que la dirección no cubre (la talla, una nota de regalo) el comprador lo manda con `neblla.inbox.send({ message, data, thread })`, donde `data` admite JSON arbitrario; lo lees con `neblla_list_communications` y respondes en el **mismo `thread`** con `neblla_send_communication`: es tu atención al cliente, sin montar ningún endpoint. El buzón guarda 100 mensajes en free y 2.000 en Pro. **5. Quién compró y qué le debes.** `neblla_list_users` y `neblla_search_users_by_email` te dan al comprador, y `purchases` va por usuario. Para marcar un `consumable` como servido, `neblla_consume_purchase`. Cuidado con `neblla_update_user_data`: es un **reemplazo completo** del documento del usuario, no un merge — lee, modifica y vuelve a escribir entero, o pierdes lo demás. **6. El sitio.** Los pedidos viajan por el buzón, que tiene su propio tope por usuario: **100 mensajes** en gratis y **2.000** en Pro. Lo que la app guarde con `db.save()` —carrito, preferencias, historial de compras— va a la base de datos de la app (50 MB por cuenta listos para usar, compartidos por sus apps gratis; 100 MB en un proyecto Pro, o el tuyo con `neblla_byodb`); si la tienda guarda más de 10 KB por usuario, sube el límite antiabuso a lo que necesite. --- Capítulo IA de la guía Neblla — neblla.ai.prompt(), presets, rutas de pago y entrega diferida. El contrato base está en core.txt; el criterio de cuándo usar Neblla, en empezar.txt. # IA integrada Llamadas a la IA desde la app sin montar servidor propio, sin gestionar claves en backend, sin rate limiting manual. El proveedor lo eliges tú: **Claude** (por defecto), **OpenAI** o **DeepSeek**; `neblla.ai.prompt()` funciona igual con los tres. ```javascript const res = await neblla.ai.prompt('Estoy en una sala oscura con una puerta cerrada. ¿Qué hago?', { preset: 'pista' }); console.log(res.text); ``` Firma: `neblla.ai.prompt(text, { preset?, model?, provider?, userToken? })` **(CLIENT)** — devuelve `Promise<{ text, usage, quota }>`. ## Proveedores y modelos `ai.provider` elige el proveedor de la app: `'claude'` (por defecto), `'openai'` o `'deepseek'`, en Config > IA o con `neblla_update_app({ ai: { provider, model, ... } })` (el objeto `ai` se reemplaza entero). Cada uno con sus modelos: - **Claude:** `opus-latest`, `sonnet-latest` (por defecto), `haiku-latest`. - **OpenAI:** `gpt-5`, `gpt-5-mini` (por defecto), `gpt-5-nano`. - **DeepSeek:** `deepseek-chat` (por defecto), `deepseek-reasoner`. Cuando pagas tú, Neblla usa tu clave **de ese proveedor**: la de Claude se guarda en tu cuenta (Cuenta > Claude), las de OpenAI y DeepSeek en su tarjeta de Config > IA; todas cifradas. Sin clave guardada, la llamada responde `no_developer_key`. Los errores del proveedor llegan como `claude_error:`, `openai_error:` o `deepseek_error:`. El `provider` de la llamada solo vale cuando paga el usuario (con su propia clave de ese proveedor); con tu clave, otro proveedor que el de la app se rechaza con `provider_not_allowed`. ## Presets Los `preset` son prompts que el desarrollador configura en el dashboard (p. ej. el preset `pista` lleva el prefijo "Eres el narrador de una aventura. Da una pista sutil sin desvelar la solución..."). Editables en el dashboard sin redeploy. ```javascript // ❌ Mal — el prompt completo en cliente: neblla.ai.prompt('Eres el narrador de una aventura. Da una pista... ' + userQuestion); // ✅ Bien — preset en el dashboard, solo la pregunta del usuario: neblla.ai.prompt(userQuestion, { preset: 'pista' }); ``` El preset prefix se aplica server-side (en rutas con clave del dev) y queda privado. ## Las tres rutas Neblla elige la ruta según **un solo** ajuste de la app, `ai.userTokenMode`, no por cómo se llame a `neblla.ai.prompt()`. Vía MCP es `neblla_update_app` con `ai: { userTokenMode: 'off' | 'browser' | 'server' }`. Lee bien los valores — `'off'` es el que paga el **dev**: 1. **Browser-directo** (`userTokenMode: 'browser'`) — el usuario aporta su propia clave; la llamada sale del navegador al proveedor (Anthropic u OpenAI) directamente, sin pasar por Neblla. DeepSeek no se llama desde el navegador: con DeepSeek, las claves de los usuarios van por el modo `server` (pedir `browser` con DeepSeek responde `invalid_ai_browser_provider`). El dev no paga tokens, no consume cuota de Neblla, no requiere login. El preset prefix queda visible en el bundle del cliente. 2. **Servidor con clave del dev** (`userTokenMode: 'off'` — el valor por defecto; "off" significa sin token DEL USUARIO, o sea que se usa la clave del dev) — la llamada va por el servidor de Neblla con la clave de API del dev. Cada usuario tiene una cuota diaria de tokens, encendida por defecto (`limitsEnabled`, 10.000 tokens al día con `tokensPerDay`; pasarse responde `quota_exceeded`): así un usuario no te vacía la clave. Se apaga con `limitsEnabled: false`. Requiere login. El modelo del panel (`ai.model`) es el tope: el `model` de la llamada puede ser ese o uno más barato del mismo proveedor (Haiku < Sonnet < Opus; nano < mini < gpt-5; deepseek-chat < deepseek-reasoner); uno más caro se rechaza con `model_not_allowed`, sin llamar al proveedor. 3. **Servidor con clave del usuario** (`userTokenMode: 'server'`) — el usuario aporta su clave (se pasa en el `userToken` del call), pero la llamada va por el servidor de Neblla para que el preset prefix quede privado. El dev no paga tokens. Requiere login. En `browser` y `server` paga el usuario: una llamada sin `userToken` se rechaza con `missing_user_token` y nunca cae en la clave del dev. En esos modos el usuario elige el proveedor y el modelo, porque lo paga él. ## Coste en cuota Cada llamada por servidor consume 500 unidades de la cuota diaria de la app (los tokens del proveedor se facturan aparte, contra la clave del dev o del usuario). El modo `browser` no consume cuota. Tabla completa de cuotas en publicar.txt. ## El consumo, a la vista El panel (Funciones › IA y Dinero › Plan y uso) y `neblla_get_app` (en `aiUsage`) enseñan lo que lleva gastado la IA de la app: hoy, este mes (UTC) y los últimos 30 días, y día a día en el panel. Para cada periodo: `calls` (llamadas que respondió el proveedor), `tokensIn` y `tokensOut`, `refused` (rechazadas antes de llegar al proveedor, sin coste: `refusedBy` dice por qué, p. ej. `quota_exceeded`, `no_developer_key`, `model_not_allowed`, `login_required`), `failed` (el proveedor respondió un error; ya pagó su coste fijo: `failedBy`) y `credits` (lo que costó en la cuota de la app). Separa lo que va con tu clave (`dev`), con la clave de cada usuario a través de Neblla (`user`) y la revisión con IA de la comunidad (`prescreen`, también con tu clave). `lifetime` da los tokens y llamadas de siempre que contó la cuota, y `creditsPerCall` lo que cuesta una llamada. `ai` dice el proveedor (`provider`, `providerName`) y si tienes guardada tu propia clave para él (`ownKey`, nunca la clave): con ella el panel pone «Tu IA · OpenAI» (o el proveedor que sea); sin ella, «Falta tu clave de OpenAI» (no hay una clave de Neblla para la IA de una app: las llamadas responden `no_developer_key`); y si paga la clave de cada usuario (`userTokenMode` `server` o `browser`), «Clave de cada usuario · OpenAI». Lo que cobra Neblla es solo eso: los créditos de la cuota de la app, y `euroPerCredit` / `eurosPerCall` su precio en euros al precio del paquete de cuota (14.000 créditos por 10 €). A eso súmale lo que te cobre tu proveedor de IA por los tokens, en la clave que pagó: la tuya o la de cada usuario (`ai.userTokenMode`). Neblla no lleva una tabla de precios de los proveedores: mira la suya. El asistente de crear una app y «+ Añadir funciones» enseñan la misma cuenta en la tarjeta de la IA (`POST /api/backend/ai-price`, sin app: `{ creditsPerCall, euroPerCredit, eurosPerCall, eurosPer1000Calls, currency, pack }`). El modo `browser` no pasa por Neblla y no se cuenta. Los días se guardan 90 días; un borrador (pre) cuenta para su app. Por HTTP, con la sesión del panel: `POST /api/backend/apps//ai-usage` con `{ days? }` (1–90, 30 por defecto). ## Entrega diferida Si la conexión se cae mientras la IA piensa, la respuesta se entrega cuando el usuario reconecta (dentro de 24h). El resultado llega por `neblla.ai.on('reply', cb)` **(CLIENT)**, sin código especial. Si Neblla se reinicia (un deploy) con la llamada en vuelo, esa llamada termina con el error `ai_interrupted` en pocos segundos (no se pierde en silencio): la app puede repetirla. Con la clave del usuario en el navegador, una red que cae da `claude_network_error`/`openai_network_error` y un proveedor que no contesta en 120 s da `ai_timeout`. Una consecuencia que conviene conocer: un `await neblla.ai.prompt(...)` que tarde más de 120 segundos ya ha rechazado con `ai_timeout` cuando llega la respuesta tardía, y esa respuesta se entrega **solo** por `neblla.ai.on('reply')`. Si tu app puede quedarse esperando dos minutos, escucha el evento además de hacer `await`. El servidor da 90 segundos al proveedor (y reintenta dos veces un 429, 503 o 529 dentro de ese tiempo); si no contesta, la llamada rechaza con `claude_timeout` (`openai_timeout`, `deepseek_timeout`), antes de los 120 segundos de arriba. Desactiva el botón mientras esperas: dos clics son dos llamadas. --- Capítulo nube de la guía Neblla — guardar ficheros en el Google Drive o el Dropbox de una persona, o en los tuyos. El contrato base está en core.txt; el criterio de cuándo usar Neblla, en empezar.txt. # Guardar en tu nube (`neblla.cloud`) Módulo opcional `cloud` (se enciende en el panel o con `neblla_update_app`). Una app guarda un fichero (un vídeo, un PDF, una foto original) en el **Google Drive** o el **Dropbox** de quien la usa, o en los del developer. Los bytes **no pasan por Neblla**: van del navegador al proveedor (Google), o del navegador a un almacén temporal de Neblla desde el que Dropbox lo recoge y se borra (Dropbox). Neblla solo concede el permiso y comprueba el resultado. ## Para qué sirve (y qué no) - Sí: «guardar mi partida/vídeo/PDF en mi Drive», recoger el consentimiento firmado de cada cliente en el Drive del fisio, un informe desde el servidor. - No: no es el almacén de la app (para eso están `db.save` y `neblla.media`); no lee ficheros de la persona ni de su carpeta, solo escribe en la carpeta de la app (ver «La carpeta de tu app» abajo). ## Dos dueños 1. **La nube de la persona** (`to: 'mine'`, por defecto). La persona la enlaza con una ventana de Neblla y decide por app. La app nunca ve un token. Sin Login de Neblla es un enlace «solo esta vez» (dura una hora, no se recuerda nada). 2. **La nube del developer** (`to: 'app'`). La conecta el developer en Conexiones › «Tu nube» (o `neblla_projects` `connect_cloud`, que da el enlace del panel: nunca se escribe un token). Un servidor real (propio o en la nube) siempre puede usarla; un cliente de jugador, y un Fog (que es un dispositivo de jugador), solo si el developer lo permite con `neblla_projects` `cloud_settings` (`fromClient`, por defecto no), por defecto solo con Login (`loggedInOnly`), y con límites por fichero y por usuario y día. ## Uso ```javascript // Desde un clic (abre una ventana): const { email } = await neblla.cloud.connect('google'); // o 'dropbox' const up = neblla.cloud.put('google', blobOFile, { name: 'viaje.mp4', folder: 'vacaciones' }) .on('progress', ({ sent, total }) => bar.value = sent / total); const r = await up; // { provider, id, name, size, verified, link? | path? } // up.abort() lo cancela. neblla.cloud.providers(); // [{ id, name, available, linked: { email, remembered } | null }] neblla.cloud.disconnect('google'); // En la nube del developer (también desde room.js en un servidor real): await neblla.cloud.putToApp(bytes, { name: 'consentimiento-ana.pdf', folder: 'clientes/ana' }); ``` `source`: un `Blob`/`File`, un `ArrayBuffer`/`Uint8Array`, un `ReadableStream` (con `size`) o una URL. `folder`: hasta cuatro niveles, sin `..`. La carpeta de la app es siempre la **del que llama**: una app no puede escribir en la de otra. Leer lo que hay y comparar (solo dentro de la carpeta de *esta* app, mismas reglas de `folder` y mismo enlace que `put`): ```javascript const { folders, files } = await neblla.cloud.list('dropbox', '2026-11/Imagenes'); // folders: ['sub', …]; files: [{ name, size, hash, modified }, …] — todos los ficheros, aunque se repitan los nombres (Drive). // Una carpeta que no existe es una carpeta vacía; listar nunca crea carpetas. // hash: Dropbox → su content_hash ('blocks'); Google → SHA-256 ('whole'); null si el proveedor no lo da. const h = await neblla.cloud.hash(file, 'blocks'); // 'blocks' (Dropbox) | 'whole' (Google): hex en minúsculas neblla.cloud.cleanName('Foto: playa/1.jpg'); // 'Foto playa1.jpg': el nombre como lo escribe el servidor ('' si no queda nada) ``` - `list(provider, folder?)` → `{ folders: [name], files: [{ name, size, hash, modified }], root: [segmentos] }`. `root` es la carpeta de la app tal como la ve la persona en su nube (`['Apps', 'Neblla', 'carpeta']` en Dropbox, `['Neblla', 'carpeta']` en Google Drive): úsalo para enseñar dónde quedan los ficheros (traduce `Apps` / la raíz tú). Listar no crea ni fija nada. Errores como `put` (`cloud_not_linked`, `cloud_consent_required`, `invalid_folder`…). - `hash(blobOFile, kind)` → hex en minúsculas. `'blocks'` es el `content_hash` de Dropbox (SHA-256 de los SHA-256 de cada bloque de 4 MB) y `'whole'` el SHA-256 del fichero (el `sha256Checksum` de Google). Usa WebCrypto bloque a bloque; sin él, un SHA-256 propio. Sirve también para comparar entre dispositivos. - `cleanName(name)` → el nombre tras la misma normalización que aplica el servidor a carpetas y ficheros (sin `/`, `:`, etc.; máx. 60 caracteres). Úsalo para comparar nombres con lo que `list` devuelve, sin distinguir mayúsculas. - `put` resuelve también con `remotePath` (Dropbox): la ruta real, distinta de `path` si Dropbox renombró el fichero porque ya existía. ## Recetas **«Guardar en mi Drive» junto a una descarga privada** (fotos, partituras, un ebook que la persona compró). `media.download` da un enlace firmado de 5 minutos y `put` acepta una URL: el fichero va del almacén al Drive de la persona sin pasar por tu app ni por Neblla. ```javascript saveBtn.onclick = async () => { const d = await neblla.media.download(mediaId); // { url, name, mime, bytes } (CLIENT, login) await neblla.cloud.connect('google'); // solo si aún no está enlazado const r = await neblla.cloud.put('google', d.url, { name: d.name, mime: d.mime, folder: 'compras' }); status.textContent = r.link ? 'Guardado: ' + r.link : 'Guardado'; }; ``` El almacén del original debe dejar leer el enlace firmado desde la web de tu app (CORS `GET`); si no, `put` falla con `source_unreachable`. Para un fichero que no cabe en memoria, deja que el navegador haga el `fetch` y pasa el cuerpo como `ReadableStream` con `size`. **Una app que recoge documentos en el Drive del developer** (consentimientos, informes, currículos). La persona no necesita cuenta de nube: tú conectas la tuya una vez en Conexiones > «Tu nube» (o con `neblla_projects`) y apuntas cada fichero a `to: 'app'`: ```javascript // Cliente (hay que marcar «dejar que los usuarios de esta app guarden aquí»; con login por defecto): const r = await neblla.cloud.putToApp(file, { name: `cv-${Date.now()}.pdf`, folder: 'candidaturas' }); // Servidor real (room.js en tu host): siempre permitido, sin ese permiso. await neblla.cloud.putToApp(bytes, { name: 'informe.pdf', folder: 'informes/' + mes }); ``` La carpeta es `Neblla//…` en tu Drive; la persona nunca ve tu nube y los límites diarios (`fileBytes`, `perUserDayBytes`, `appDayBytes`) protegen tu espacio. ## Integridad El SDK calcula el SHA-256 (Google) o el `content_hash` de bloques de 4 MB (Dropbox) mientras sube y lo compara con el que dice el proveedor. Si no cuadra, Neblla borra la copia y el `put` falla con `cloud_checksum_mismatch`. Si Google aún no da el hash, el `put` termina con `verified: false` (la copia se queda). ## Errores `cloud_not_linked` · `cloud_consent_required` (la persona no ha permitido a *esta* app) · `cloud_relink` (el proveedor cortó el enlace: volver a conectar) · `cloud_quota` (su Drive/Dropbox está lleno) · `cloud_checksum_mismatch` · `upload_incomplete` (el navegador no pudo leer el fichero entero: en iOS una foto elegida puede llegar vacía o cortada; hay que volver a elegirla) · `size_mismatch` (lo que llegó al almacén intermedio de Neblla no tiene el tamaño declarado; no se guarda nada) · `cloud_busy` (3 subidas a la vez por conexión) · `file_too_large` · `invalid_file` · `cloud_exists` (la ruta ya estaba ocupada en Dropbox) · `invalid_if_exists` · `empty_file` (el fichero pesa 0 bytes: casi siempre es un fichero que no cargó; si de verdad quieres uno vacío, `put(..., { allowEmpty: true })`) · `invalid_folder` · `provider_unavailable` · `cloud_dev_not_connected` · `cloud_from_client_off` · `login_required` · `cloud_limit_user` · `cloud_limit_app` · `cloud_session_expired` · `cancelled` (la ventana se cerró) · `popup_blocked` · `feature_disabled` (módulo `cloud` apagado). **Reintentar sin duplicar (`ifExists`):** `put(..., { ifExists: 'skip' })` mira la carpeta antes de subir: si ya hay un fichero con ese nombre no sube nada ni gasta cuota de subida, y la promesa resuelve `{ provider, skipped: true, name, size, path, remotePath }` (útil tras un `cloud_unreachable` cuyo último trozo sí llegó). `ifExists: 'rename'` guarda como `nombre (2).ext`, `nombre (3).ext`… el primero libre. Sin la opción, todo como siempre (Google crea un duplicado homónimo). `replace` no existe (en Dropbox sería borrar y escribir otra vez, sin atomicidad). El proveedor que no sabe mirar la carpeta sube sin comprobar. Dos clics seguidos en «Guardar» (mismo fichero, misma carpeta, misma persona, menos de 5 min) comparten la misma subida: no se abren dos. Valor desconocido: `invalid_if_exists`. Si Dropbox encuentra la ruta ocupada al cerrar la subida, el error es `cloud_exists` (antes `cloud_provider_error`). **Cortes de red:** `cloud.put` no se rinde a la primera. Cada trozo que falla (sin red, 429, 5xx) se manda otra vez con espera creciente (o la de `Retry-After`) hasta ~3 minutos seguidos fallando; si el navegador dice que no hay red, espera al evento `online` y ese tiempo no cuenta. En Google la subida sigue donde se quedó (la sesión dura 7 días). Solo si el corte pasa de ~3 minutos sale `cloud_unreachable`: la app puede ofrecer «Reintentar». Las subidas a Dropbox de más de una hora ya no pierden lo subido (las URL de R2 se piden otra vez si caducan). ## La carpeta de tu app Los ficheros de tu app caen en `Apps/Neblla/` (Dropbox) y `Neblla/` (Google Drive), donde `` es la carpeta corta de la app. Por defecto, en las apps creadas desde el 2026-11-11, es su slug (si está libre) y se fija la primera vez que la app guarda; las apps anteriores (y las que no tienen slug libre) siguen con la forma antigua ` []` hasta que su dueño elija un nombre. Para elegirla: `neblla_update_app({ appId, cloudFolder: 'transfer' })` o el panel, Conexiones › «Tu nube» › «Carpeta en la nube». Reglas: 1 a 40 caracteres, minúsculas, cifras y `-`, sin palabras reservadas; única entre **todas** las apps de Neblla, y un nombre nunca se libera ni se reutiliza (tampoco si la app se borra). Solo se puede cambiar hasta que la app guarda su primer fichero en la nube de alguien (o alguien la enlaza): después `cloud_folder_locked`. Otros errores: `invalid_cloud_folder`, `cloud_folder_taken`. Cambiarla no mueve nada: lo ya guardado se queda en la carpeta antigua. La pre de una app usa la misma carpeta que su pro. ## Privacidad La app nunca recibe un token de la persona ni del developer; los tokens de larga duración se guardan sellados y el enlace de la persona se ve y se quita en su cuenta › Permisos › «Tus nubes». Google solo da acceso a los ficheros que Neblla crea (`drive.file`); Dropbox, a la carpeta `Apps/Neblla`. --- Capítulo Mundo de la guía Neblla — el motor 3D: escena, cámaras, controles, física, eventos, modelos, el catálogo de piezas y el muñeco. El contrato base está en core.txt; el criterio de cuándo usar Neblla, en empezar.txt. # Mundo, el motor 3D **Mundo** es el motor 3D de Neblla (el nombre no se traduce; en el código es `neblla.world`). Lo usas desde `client.js` para un juego, una app o una web: un plataformas, un juego en tercera persona, una maqueta de un piso o un visor 3D de un producto en una tienda. Dibuja con three.js y simula con Rapier, y ya viene con luz, cielo, sombras, cámaras y controles que se ven bien sin tocar nada. Tú escribes las reglas; Mundo pone la escena, la física y los controles de teclado, ratón, mando y pantalla táctil. Requiere el módulo `world` encendido en Config → Módulos (o `neblla_update_app` con `features: { world: true }`). Está **apagado por defecto**. Con el módulo apagado, `neblla.world.create()` rechaza con `feature_disabled`. El motor es un fichero aparte del SDK: se descarga la primera vez que la página llama a `neblla.world.create()`, nunca antes. Una página sin 3D no lo paga. Son unos 1,8 MB comprimidos (la física es la mayor parte), en caché para siempre. ```javascript const world = await neblla.world.create({ container: '#juego', sky: 'day', camera: 'third' }); world.add({ shape: 'box', size: [20, 1, 20], position: [0, -0.5, 0], color: '#7fa65a' }); const yo = world.add({ character: true, position: [0, 1, 0] }); world.control(yo); // el teclado, el ratón, el mando o el joystick táctil lo mueven; la cámara lo sigue ``` `neblla.world.create(opts)` **(CLIENT)** — devuelve `Promise`. Opciones: - `container`: el elemento (o su selector) donde va el lienzo; el lienzo ocupa todo el contenedor y lo sigue al cambiar de tamaño. **Dale una altura con CSS** (un `div` vacío mide 0). Sin `container`, ocupa la ventana entera. - `sky`: `'day'` (por defecto), `'sunset'`, `'night'` o `'studio'` (luz neutra, sin niebla y un suelo que solo muestra la sombra: para un producto). Cada cielo trae su luz, su niebla y su sombra. - `camera`: un preajuste (`'side'`, `'top'`, `'iso'`, `'third'` por defecto, `'first'`, `'chase'`) o `{ preset, distance, height, yaw, pitch, target }`. - `quality`: `'auto'` (por defecto), `'high'`, `'medium'`, `'low'` o `'lowest'`; se cambia luego con `world.quality.set()`. - `fog`: `[color, cerca, lejos]`, `{ color, near, far }` o `false`; la del cielo por defecto. `far`: hasta dónde ve la cámara (1000). `shadow: { range }`: los metros que cubre la sombra (20). Ver «Mundos grandes en un móvil». - `touch`: `'auto'` (por defecto: el joystick y los botones salen en un móvil o una tableta), `true` o `false`. - `gravity`: `[x, y, z]`, por defecto `[0, -9.81, 0]`. - `lock`: un eje que nada puede dejar, como `'z'`. Con `camera: 'side'` es `'z'` por defecto: el plataformas es el mismo mundo visto de lado. - `fallY`: por debajo de esta altura salta `fall` (por defecto `-30`). - `headless: true`: solo la simulación, sin dibujo (también en Node). ## Las capas Mundo va por capas y puedes bajar de capa cuando quieras: `world.three` es three.js (`{ THREE, scene, camera, renderer }`), `world.rapier` es Rapier y `world.sim` es la simulación sin dibujo. Lo que Mundo no trae lo añades tú con three.js o Rapier sobre la misma escena. `await neblla.world.engine()` devuelve el módulo del motor (`createWorld`, `PRESETS`, `SKIES`, `STEP`…). ## Cosas: formas, cuerpos y modelos `world.add(spec)` **(CLIENT)** — añade una cosa y la devuelve. Es síncrono. - Forma: `shape: 'box'` con `size: [ancho, alto, fondo]`, `'sphere'` con `radius`, `'capsule'` con `radius` y `height`, `'convex'` con `points` o `'mesh'` con `vertices` e `indices`. - Cuerpo: `body: 'static'` (por defecto: suelo, paredes), `'dynamic'` (cae, rueda, choca), `'kinematic'` (lo mueves tú: una plataforma que va y viene) o `'none'` (solo se ve). - Sitio: `position: [x, y, z]` (metros; 1 unidad = 1 metro), `rotation: [x, y, z]` (radianes). - Aspecto: `color` (`'#ffd23f'` o `0xffd23f`), `material: 'matte'` (por defecto), `'glossy'`, `'metal'` o `'emissive'`, `glow`, `opacity`, `visible`. - Física: `friction`, `restitution` (rebote), `density`, `lock` (ejes que esta cosa no deja, como `'xz'`). - Zonas: `sensor: true` (no choca, avisa de quién entra y sale) y `collect: true` (una moneda: la recoge un personaje, salta `collect` y desaparece; con `keep: true` se queda). - `name` y `data`: lo tuyo. `world.find(name)` la busca. La cosa devuelta tiene `id`, `name`, `data`, `object` (su objeto de three.js), `position` y `velocity` (leer y escribir, `[x, y, z]`), `rotation` (un cuaternión `{ x, y, z, w }`; se escribe también en radianes), `impulse([x, y, z])` (un empujón a un cuerpo `dynamic`), `moveTo(position, rotation?)` (el siguiente sitio de un cuerpo `kinematic`, que empuja lo que encuentra) y `remove()`. ### Personajes `world.add({ character: true, position, speed: 5, runSpeed: 8, jump: 6.5, radius: 0.35, height: 1.8 })` — una cápsula con el controlador de personaje de Rapier: sube escalones (`step`, 0,35 m), sube pendientes hasta `slope` grados (50), se pega al suelo al bajar y salta con margen (un poco después de dejar un borde y un poco antes de tocar el suelo). `grounded` dice si pisa suelo. `world.control(personaje)` — los controles lo mueven y la cámara lo sigue. Sin `control()`, lo mueves tú con `personaje.input = { x, z, jump, run }` (`x` y `z` entre −1 y 1, en los ejes del mundo). ## Cámaras `world.camera.use(preajuste, { target, transition, distance, height, yaw, pitch })` **(CLIENT)** — cambia de cámara, también a mitad de partida, con una transición suave (`transition`: segundos, 0,6 por defecto; 0 es un corte). `target` es una cosa o un punto `[x, y, z]`; con `control()` es el personaje. | Preajuste | Para | Controles | |---|---|---| | `side` | plataformas, de lado | izquierda y derecha, saltar | | `top` | una arena, desde arriba | las cuatro direcciones en el plano | | `iso` | una granja, estrategia | las cuatro direcciones, en diagonal como se ve | | `third` | tipo Roblox, un visor de producto | hacia donde mira la cámara; arrastrar con el botón derecho gira (con el izquierdo también en `third`) y la rueda acerca | | `first` | primera persona | el ratón queda capturado y mira; WASD camina | | `chase` | carreras | arriba acelera, los lados giran | `world.camera.preset` dice cuál está puesta y `world.camera.orbit` (`{ yaw, pitch, zoom }`) es el giro que mueven los controles. ## Controles Teclado (WASD o flechas, espacio salta, Mayús corre, E o Intro es la acción), ratón (**arrastrar con el botón derecho gira la cámara**, como en Roblox, sin el menú del navegador; en `third` también con el izquierdo, y en `chase` la cámara se queda donde la dejas, y al andar «adelante» es hacia donde mira la cámara; **doble clic con el derecho** la pone otra vez detrás; en `first` el ratón queda capturado), mando (stick izquierdo mueve, el derecho mira, A salta, X acción) y, en pantallas táctiles, un joystick a la izquierda y los botones de saltar y de acción a la derecha; un dedo en el resto de la pantalla gira la cámara. Cada preajuste de cámara trae sus controles. `world.player.action` dice si la acción está pulsada. ## Eventos y temporizadores Los nombres son fijos: son los mismos que usarán los géneros en JSON. - `world.on('touch', (a, b) => …)` — dos cosas se tocan (empiezan a tocarse). - `world.on('enter', (zona, cosa) => …)` y `world.on('leave', (zona, cosa) => …)` — algo entra o sale de un `sensor`. - `world.on('collect', (moneda, quien) => …)` — un personaje recoge un `collect`. - `world.on('fall', (cosa) => …)` — algo cae por debajo de `fallY`. - `world.on('step', (dt) => …)` — cada paso de la simulación: aquí van las reglas. Cada cosa tiene los suyos: `cosa.onTouch(fn)`, `cosa.onEnter(fn)`, `cosa.onLeave(fn)`, `cosa.onCollect(fn)`, `cosa.onFall(fn)`. Todos devuelven una función que lo quita. `world.after(segundos, fn)` y `world.every(segundos, fn)` — temporizadores en el reloj de la simulación, no en el de la pared: la misma partida da los mismos tiempos. Devuelven una función que los cancela. `world.time` es el tiempo simulado. `world.onFrame((dt) => …)` — cada dibujo, para lo que solo se ve (una pieza que gira en un escaparate), nunca para las reglas. ## La simulación La física va a 60 pasos por segundo fijos y el dibujo, a lo que dé la pantalla, entre los dos últimos pasos. Mundo usa la versión determinista de Rapier: la misma simulación, con las mismas entradas, da el mismo estado en cualquier dispositivo. `world.state()` devuelve el sitio, el giro y la velocidad de cada cosa, y `world.hash()`, una huella corta de ese estado: dos dispositivos que la comparan saben si van iguales. El multijugador está más abajo, en «Multijugador». `world.stop()` y `world.start()` paran y siguen el bucle; `world.update(dt)` avanza a mano y `world.step()`, un paso. `world.destroy()` lo quita todo. ## Calidad automática Con `quality: 'auto'` Mundo mide los fotogramas por segundo: si no llega a 45 baja la nitidez y las sombras, y si pasa de 58 las sube. En un móvil empieza más ligero. `world.quality.level` dice el nivel de ahora. Cada nivel tiene también un presupuesto de draw calls (400, 250, 150 y 100, de `high` a `lowest`): un fotograma que lo pasa cuenta como lento y baja un nivel aunque vaya a 60. **Cambiarla en marcha** (C524). `world.quality.set('auto' | 'high' | 'medium' | 'low' | 'lowest')` la cambia al momento y devuelve el nivel; `'auto'` deja otra vez que Mundo decida, desde donde esté. Es lo que llama el menú de ajustes gráficos de un juego. `world.quality.modes` lista los valores y se emite el evento `quality` (`world.on('quality', (nivel, auto) => …)`). `world.stats()` dice qué cuesta un fotograma: `{ drawCalls, triangles, fps, entities, zones, lods, quality, auto, budget, overBudget }`. `drawCalls` y `triangles` son del último dibujo (0 sin dibujo) y `fps` va suavizado. ## Efectos y sonido Para el dibujo y el oído, nunca para las reglas: no tocan la simulación, así que dos dispositivos que no coinciden en una salpicadura siguen coincidiendo en el juego. `world.effect(nombre, { at, follow, color, scale, count, loop })` lanza partículas dibujadas en la tarjeta gráfica (un solo draw call por efecto). Los nombres: `splash` (salpicadura), `spark` (chispas), `sparkle` (destellos que se quedan flotando), `smoke` y `dust`. `at` es `[x, y, z]` o una cosa (un barco que salpica); `follow` hace que el efecto siga a una cosa mientras vive; `color` es un número (`0xffaa00`) o `'#ffaa00'`; `scale` agranda; `count` cambia cuántas (hasta 200; la calidad deja un 100 %, 70 %, 50 % o 30 %); `loop: true` no acaba hasta `stop()`. Devuelve `{ stop(), done, count, object }`; acaba solo, y `world.effects` lista los vivos. Un nombre que no existe, sin sitio, o con `scale`/`count` fuera de rango falla con `world_bad_effect` diciendo qué escribir. `world.sound(nombre | dirección | hoja.json, { at, follow, loop, loopStart, loopEnd, volume, rolloff })` suena **desde su sitio** (Web Audio con un panner; el oyente sigue a la cámara). Sin `at` ni `follow` suena sin posición (música, menús). Los sonidos de Neblla, generados por Neblla —sin ficheros ni licencias que citar— son `splash`, `hit`, `slash`, `coin`, `step`, `wave` y `gull`; con una dirección (`/media/olas.mp3`, una URL) suena cualquier sonido de tu app. Arranca tras el primer toque o tecla de la página (el navegador no deja antes); lo que se pide antes suena en cuanto se puede. Con la **hoja `.json` que escribe Eco** (la de una canción o una música de fondo) basta una dirección: Mundo escoge la fuente más ligera que el aparato sabe tocar (Opus antes que MP3) y, con `loop: true`, repite **entre los puntos de esa fuente** sin salto (`AudioBufferSourceNode`, no `