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)

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


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


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)

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.


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':


// 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/<carpeta de tu app>/… 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/<nombre> (Dropbox) y Neblla/<nombre> (Google Drive), donde <nombre> 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 <nombre de la app> [<id>] 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.