Capítulo identidad de la guía Neblla — login SSO, scopes, guests, db.save() y persistencia. El contrato base está en core.txt; el criterio de cuándo usar Neblla, en empezar.txt.

Identidad y persistencia

El idioma del usuario y de tu app

El SDK no expone el idioma del usuario (neblla.auth.me no lo trae). Para localizar tu propia pantalla, Neblla sirve https://neblla.com/connect/lang.js: carga el diccionario que toca y pinta la página. Solo necesitas ficheros lang/ en la app y una línea de <script>.

1. lang/config.json: { "default": "es", "on": ["es", "en", "ar"] }. on son los idiomas encendidos y default el de reserva. Sin este fichero, la app solo tiene default en (Neblla no puede listar los lang/*.json). 2. lang/<código>.json, uno por idioma de on: planos ("saludo": "Hola") o anidados ({ "menu": { "inicio": "Inicio" } }, clave menu.inicio). Los códigos: es, en, fr, de, it, pt, ja, ko, zh, ar. 3. En el HTML, antes de tu código:


<script src="https://neblla.com/connect/lang.js"></script>
<h1 data-i18n="titulo"></h1>
<input data-i18n-placeholder="nombre" data-i18n-title="nombre">
<p data-i18n-html="aviso"></p>
<div data-neblla-lang-switcher></div>
<script>
  nebllaLang.ready.then(() => {
    alert(nebllaLang.t('hola', { name: 'Ana' }));   // "hola": "Hola, {name}"
  });
</script>

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 <html> (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_<categoría> (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 (<h1 data-i18n="title">Hola</h1>); es el de reserva hasta que llega el diccionario, y lang.js solo lo sustituye cuando hay traducción. Mientras carga, <html> 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 <span data-i18n>. 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 <html lang> 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:

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/<appId>/auth/token Authorization: Bearer <clave secreta> { "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.


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:

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.


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:

db.save() y db.data


neblla.db.save({ record: 1250, settings: { sonido: false } });

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


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

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:


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.


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


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.


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:


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.


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 });

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.


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

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

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

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


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' },
} })

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/<appId>/tables/<tabla>/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 <app>_<tabla> por el nombre que te da «Usar con n8n»; haz copia antes):


-- Postgres: cambiar el tipo de una columna (después, vuelve a declararla con el tipo nuevo)
ALTER TABLE "<app>_puntuaciones" ALTER COLUMN "puntos" TYPE BIGINT USING "puntos"::BIGINT;
-- MySQL
ALTER TABLE `<app>_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 "<app>_puntuaciones" ADD COLUMN "puntos2" REAL;
UPDATE "<app>_puntuaciones" SET "puntos2" = "puntos";

-- Borrar una columna que ya retiraste (Postgres, MySQL y SQLite 3.35+)
ALTER TABLE "<app>_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 "<app>_puntuaciones" ADD COLUMN "nivel" VARCHAR(255);
UPDATE "<app>_puntuaciones" SET "nivel" = "modo";

-- Un índice propio para tus consultas (Neblla ya tiene uno en nb_owner)
CREATE INDEX "<app>_puntuaciones_puntos" ON "<app>_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/<appId>/tables/<tabla>/n8n) te da el nombre SQL, las columnas, los datos de conexión sin contraseña y un SELECT listo:


-- el ranking: la mejor puntuación de cada modo (n8n: nodo Postgres / MySQL / SQLite → «Execute Query»)
SELECT "modo", MAX("puntos") AS "mejor" FROM "<app>_puntuaciones" GROUP BY "modo" ORDER BY "modo";
-- recuento de votos de hoy por tema
SELECT "tema", COUNT(*) AS "votos" FROM "<app>_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.


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

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.


// 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

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»).


// ❌ 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:


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
} })

// 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 });

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:


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)
} })

// 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)

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/<appId>/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/<appId>/broadcast/estimate  { authToken, message, data?, group?, role? }
→ { recipients, perRecipient, credits, available, ceiling, percentOfDay, fits, reachable }
POST /api/backend/apps/<appId>/broadcast/send      (lo mismo) → { broadcast, estimate }
POST /api/backend/apps/<appId>/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.