API JavaScript

Firma: device.getInfo(options?) → Promise<DeviceInfo>. Sin parámetros nativos ni permisos.

Resultado: { model: string, manufacturer: string, osVersion: string, sdk: number, platform: "android" }. Los valores vienen de los campos Build de Android y cambian según el dispositivo; sdk es su nivel de API.

import { device } from "/__koru/core.mjs";
const info = await device.getInfo();
console.log(
  `${info.manufacturer} ${info.model} · Android ${info.osVersion} (API ${info.sdk})`,
);

options admite timeout y signal, explicados en invoke(). Un plugin desactivado rechaza con METHOD_NOT_FOUND; el canal y el tiempo de espera también pueden producir errores.

Firma: app.getInfo(options?) → Promise<AppInfo>. Sin parámetros nativos ni permisos.

Resultado: { appId: string, name: string, version: string, versionCode: number }, tomado del koru.json con el que se generó el APK.

import { app } from "/__koru/core.mjs";
const info = await app.getInfo();
document.querySelector("#version").textContent = `${info.name} ${info.version}`;

El objeto describe la app empaquetada. No consulta una tienda ni versiones disponibles.

Firma: storage.get(key: string, options?) → Promise<string | null>.

Argumentos: key debe ser una clave válida. Resultado: el string guardado, o null si nunca existió o fue eliminado.

import { storage } from "/__koru/core.mjs";
const theme = (await storage.get("theme")) ?? "system";
console.log(theme);

Una clave ausente, de tipo incorrecto o inválida rechaza con INVALID_REQUEST. Este wrapper extrae por ti el valor del objeto nativo { value }.

Firma: storage.set(key: string, value: string, options?) → Promise<{}>.

Argumentos: clave válida y valor string. Android confirma el guardado antes de resolver la promesa. Resultado: objeto vacío {}.

import { storage } from "/__koru/core.mjs";
await storage.set("theme", "dark");
await storage.set("visits", String(3)); // convierte números a string

Tipos incorrectos rechazan con INVALID_REQUEST; un guardado fallido, con STORAGE_ERROR.

Firma: storage.remove(key: string, options?) → Promise<{}>. Resultado: objeto vacío una vez confirmada la eliminación. Eliminar una clave inexistente es válido.

import { storage } from "/__koru/core.mjs";
await storage.remove("theme");
console.log(await storage.get("theme")); // null

Una clave inválida rechaza con INVALID_REQUEST; un guardado fallido, con STORAGE_ERROR.

Firma: storage.clear(options?) → Promise<{}>. Elimina todas las claves del espacio privado de koru para esta app y resuelve con {}. No borra los assets web empaquetados ni otros datos Android de la app.

import { storage } from "/__koru/core.mjs";
await storage.clear();

Un guardado fallido rechaza con STORAGE_ERROR. Úsalo cuando el usuario realmente quiera borrar todas las claves.

Configuración: activa vibration en koru.json; koru añade android.permission.VIBRATE al APK.

Firma: vibration.vibrate(duration = 100, options?) → Promise<{}>. duration debe ser entero entre 1 y 10.000 milisegundos. La promesa resuelve con {} al iniciar la acción Android; no espera a que termine la vibración.

import { vibration } from "/__koru/core.mjs";
await vibration.vibrate(150);

Duraciones inválidas rechazan con INVALID_REQUEST. Un fallo de hardware o Android puede rechazar con NATIVE_ERROR; un dispositivo sin vibrador no ofrece respuesta táctil.

Configuración: activa share en koru.json. No añade permisos.

Firma: share.text(text: string, options?) → Promise<{}>. text es el string a compartir. Koru abre el selector ACTION_SEND con tipo text/plain y resuelve con {} tras lanzarlo. Eso no significa que el usuario haya elegido un destino o completado el envío.

import { share } from "/__koru/core.mjs";
await share.text("Prueba mi app koru");

Un valor que no sea string rechaza con INVALID_REQUEST; si no se puede abrir el selector puede aparecer NATIVE_ERROR.

Firma: notifications.permission(options?) → Promise<{ status: "granted" | "denied" }>.

import { notifications } from "/__koru/core.mjs";
const { status } = await notifications.permission();
console.log(status); // "granted" o "denied"

Lee el permiso y el ajuste actuales de Android. No muestra un diálogo. Un plugin desactivado rechaza con METHOD_NOT_FOUND.

Firma: notifications.requestPermission(options?) → Promise<{ status: "granted" | "denied" }>.

En Android 13/API 33+, si está denegado abre el diálogo del permiso. En Android 8–12/API 26–32, abre los ajustes de notificación de la app y resuelve al regresar. Si ya está concedido, resuelve de inmediato. El timeout predeterminado del wrapper es 120.000 ms para este método; options.timeout puede cambiarlo hasta ese límite. Solo puede haber una solicitud pendiente.

import { notifications } from "/__koru/core.mjs";
const { status } = await notifications.requestPermission();
if (status === "granted") console.log("Notificaciones activas");

BUSY indica otra solicitud pendiente; TIMEOUT, que no llegó respuesta a tiempo. denied es un resultado normal, no un error lanzado.

Firma: notifications.show({ id: number, title: string, body: string }, options?) → Promise<{}>.

id es un identificador entero; usa el mismo para reemplazar o cancelar una notificación. El valor nativo predeterminado es 1 si no pasas id, pero especificarlo aclara la cancelación posterior. title y body son strings obligatorios. La promesa resuelve con {} tras publicar, no cuando el usuario abre la notificación.

import { notifications } from "/__koru/core.mjs";
const { status } = await notifications.permission();
if (status === "granted") {
  await notifications.show({
    id: 7,
    title: "Listo",
    body: "La exportación terminó.",
  });
}

Si las notificaciones están desactivadas o falta el permiso en Android 13+, rechaza con PERMISSION_DENIED. Tipos incorrectos rechazan con INVALID_REQUEST.

Firma: notifications.cancel(id: number, options?) → Promise<{}>. Usa el mismo ID entero de show; resuelve con {} después de pedirle a Android que la cancele. Cancelar un ID ausente es válido. No abre un diálogo de permiso.

import { notifications } from "/__koru/core.mjs";
await notifications.cancel(7);

Un ID que no sea entero rechaza con INVALID_REQUEST. Un fallo nativo Android puede rechazar con NATIVE_ERROR.

Firma: alarms.schedule({ id, title, body, at }, options?) → Promise<{}>; alarms.cancel(id) → Promise<{}>; alarms.list() → Promise<string[]>, los IDs aún pendientes. at es un Date o milisegundos desde epoch. Programar un id que ya existe reemplaza la alarma anterior.

import { alarms, notifications } from "/__koru/core.mjs";
await notifications.requestPermission(); // necesario en Android 13+
await alarms.schedule({
  id: "te",
  title: "Té",
  body: "Tu té está listo.",
  at: Date.now() + 60_000,
});
console.log(await alarms.list()); // ["te"]
await alarms.cancel("te");

En Android koru usa AlarmManager.setAndAllowWhileIdle. La alarma es inexacta: puede llegar unos minutos tarde, sobre todo en reposo o en Doze. No se usan alarmas exactas porque requieren un permiso que el usuario concede en Ajustes. Las alarmas se guardan y se reprograman tras reiniciar el móvil o actualizar la app (BOOT_COMPLETED, MY_PACKAGE_REPLACED); las que vencieron mientras estaba apagado se muestran al arrancar. Al tocar la notificación se abre la app. Para mostrarse en Android 13+ hace falta el permiso de notificaciones: activa también notifications y llama a notifications.requestPermission().

En un navegador y con koru dev, las alarmas solo se disparan mientras la página está abierta (setTimeout más Notification si hay permiso). Si falta title, body o at, rechaza con INVALID_REQUEST.

Firma: browser.open(url: string, options?) → Promise<{}>. Abre el enlace en otra app: un navegador, el correo, el teléfono, etc.

import { browser } from "/__koru/core.mjs";
await browser.open("https://koru.js.org");
await browser.open("mailto:hola@example.com");

Esquemas permitidos: https, http, mailto, tel, sms, geo y market. Cualquier otro rechaza con INVALID_REQUEST. Si ninguna app puede abrir el enlace, rechaza con NATIVE_ERROR. En un navegador usa window.open. Con server en koru.json, los enlaces externos ya se abren así solos; consulta Contenido remoto.

Firma: screen.keepAwake(enabled = true, options?) → Promise<{}>. Mantiene la pantalla encendida mientras la app está visible (FLAG_KEEP_SCREEN_ON); keepAwake(false) la deja apagarse de nuevo.

import { screen } from "/__koru/core.mjs";
await screen.keepAwake(); // p. ej. mientras muestras una receta
await screen.keepAwake(false);

En un navegador usa la Screen Wake Lock API si existe; si no, rechaza con UNAVAILABLE.

Firma: clipboard.writeText(text: string, options?) → Promise<{}>; clipboard.readText(options?) → Promise<string | null>, que es null si el portapapeles está vacío.

import { clipboard } from "/__koru/core.mjs";
await clipboard.writeText("hola");
const text = await clipboard.readText(); // "hola", o null si está vacío

Desde Android 10 solo la app en primer plano puede leer el portapapeles. En un navegador usa navigator.clipboard, que puede pedir permiso o rechazar con UNAVAILABLE.

Firma: invoke(method: string, params = {}, options = {}) → Promise<object>. Es la función exportada por /__koru/core.mjs; window.Koru.invoke es el equivalente global. El método es un string como "device.info"; params debe ser un objeto simple serializable a JSON. Úsalo para un plugin personalizado o si necesitas el resultado nativo sin transformar.

import { invoke } from "/__koru/core.mjs";
const info = await invoke("device.info", {});
const raw = await invoke("storage.get", { key: "theme" });
console.log(info.model, raw.value); // raw.value es string o null

options.timeout es un número finito de milisegundos entre 1 y 120.000; por defecto 10.000. El temporizador también incluye la espera del canal nativo. options.signal admite AbortSignal; cancelar rechaza con CANCELLED. La cancelación impide una petición que aún no se envió, pero no deshace una acción nativa ya iniciada. Máximo 256 llamadas pendientes. El JSON serializado de una petición debe medir menos de 65.536 caracteres.

Resultado: el objeto devuelto por el handler nativo. Las acciones integradas devuelven {}; el wrapper storage.get() convierte el resultado bruto { value } en string o null. Los handlers personalizados definen su objeto de resultado.