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