JavaScript API

Signature: device.getInfo(options?) → Promise<DeviceInfo>. No native parameters or permissions.

Result: { model: string, manufacturer: string, osVersion: string, sdk: number, platform: "android" }. The values come from Android Build fields and differ by device; sdk is its API level.

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

options may contain the common timeout and signal described under invoke(). A disabled plugin rejects with METHOD_NOT_FOUND; channel and timeout failures can also reject.

Signature: app.getInfo(options?) → Promise<AppInfo>. No native parameters or permissions.

Result: { appId: string, name: string, version: string, versionCode: number }, from the koru.json used to build this APK.

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

The object describes the packaged app. It does not query an app store or available updates.

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

Arguments: key is a valid storage key. Result: the stored string, or null when the key has never been set or was removed.

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

A missing, wrong-type or invalid key rejects with INVALID_REQUEST. This wrapper unwraps the native { value } object for you.

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

Arguments: a valid key and a string value. The operation uses a synchronous Android commit before the Promise resolves. Result: an empty object {}.

import { storage } from "/__koru/core.mjs";
await storage.set("theme", "dark");
await storage.set("visits", String(3)); // convert numbers to strings

Invalid key/value types reject with INVALID_REQUEST; an unsuccessful commit rejects with STORAGE_ERROR.

Signature: storage.remove(key: string, options?) → Promise<{}>. Result: an empty object after Android commits the removal. Removing a key that is absent is safe.

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

Invalid keys reject with INVALID_REQUEST; a failed commit rejects with STORAGE_ERROR.

Signature: storage.clear(options?) → Promise<{}>. It clears all keys in koru's private storage namespace for this app, then resolves with {}. It does not erase packaged web assets or unrelated Android app data.

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

A failed commit rejects with STORAGE_ERROR. Use this only when the user intends to clear every key.

Setup: enable vibration in koru.json; koru adds android.permission.VIBRATE to the APK.

Signature: vibration.vibrate(duration = 100, options?) → Promise<{}>. duration must be an integer from 1 to 10,000 milliseconds. The Promise resolves with {} after starting the Android action; it does not wait for the vibration to finish.

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

A wrong duration rejects with INVALID_REQUEST. Hardware or Android failures may reject with NATIVE_ERROR; a device without a vibrator cannot provide tactile feedback.

Setup: enable share in koru.json. No added permission.

Signature: share.text(text: string, options?) → Promise<{}>. text is the string to share. Koru opens an Android ACTION_SEND chooser with MIME type text/plain and resolves with {} after launching it. Resolution does not mean the user selected a destination or completed a share.

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

Non-string text rejects with INVALID_REQUEST; failure to open the chooser may reject with NATIVE_ERROR.

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

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

This reads the current Android permission and notification setting. It does not show a prompt. A disabled plugin rejects with METHOD_NOT_FOUND.

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

On Android 13/API 33+, a denied status opens the runtime permission prompt. On Android 8–12/API 26–32, it opens app notification settings and resolves when the user returns. If access was already granted, it resolves immediately. The wrapper's default timeout is 120,000 ms for this method; options.timeout can override it up to that limit. Only one request can be pending.

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

BUSY means another request is pending; TIMEOUT means the decision did not arrive in time. A returned denied status is a normal result, not a thrown error.

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

id is an integer notification identifier; use the same ID to replace or cancel a notification. The native default is 1 if id is omitted, but passing it explicitly makes later cancellation clear. title and body are required strings. The Promise resolves with {} after posting the notification, not after the user opens it.

import { notifications } from "/__koru/core.mjs";
const { status } = await notifications.permission();
if (status === "granted") {
  await notifications.show({
    id: 7,
    title: "Ready",
    body: "Your export finished.",
  });
}

If notifications are disabled or the Android 13+ permission is absent, it rejects with PERMISSION_DENIED. Wrong parameter types reject with INVALID_REQUEST.

Signature: notifications.cancel(id: number, options?) → Promise<{}>. Pass the same integer ID used for show; it resolves with {} after asking Android to cancel that notification. An absent ID is safe to cancel. No permission prompt is shown.

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

A non-integer ID rejects with INVALID_REQUEST. A native Android failure may reject with NATIVE_ERROR.

Signature: alarms.schedule({ id, title, body, at }, options?) → Promise<{}>; alarms.cancel(id) → Promise<{}>; alarms.list() → Promise<string[]>, the IDs still pending. at is a Date or milliseconds since the epoch. Scheduling an id that already exists replaces the earlier alarm.

import { alarms, notifications } from "/__koru/core.mjs";
await notifications.requestPermission(); // needed on Android 13+
await alarms.schedule({
  id: "tea",
  title: "Tea",
  body: "Your tea is ready.",
  at: Date.now() + 60_000,
});
console.log(await alarms.list()); // ["tea"]
await alarms.cancel("tea");

On Android koru uses AlarmManager.setAndAllowWhileIdle. The alarm is inexact: it can arrive a few minutes late, especially at rest or in Doze. Exact alarms are not used because they require a permission the user grants in Settings. Alarms are stored and rescheduled after the phone restarts or the app is updated (BOOT_COMPLETED, MY_PACKAGE_REPLACED); those that came due while the phone was off are shown at boot. Tapping the notification opens the app. To be displayed on Android 13+ the notification permission must be granted: enable notifications too and call notifications.requestPermission().

In a browser and under koru dev, alarms fire only while the page is open (setTimeout plus Notification if permission was granted). A missing title, body or at rejects with INVALID_REQUEST.

Signature: browser.open(url: string, options?) → Promise<{}>. It opens the link in another app: a browser, mail, the dialer and so on.

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

Allowed schemes: https, http, mailto, tel, sms, geo and market. Any other scheme rejects with INVALID_REQUEST. If no app can open the link it rejects with NATIVE_ERROR. In a browser it uses window.open. With server in koru.json, external links already open this way on their own; see Remote content.

Signature: screen.keepAwake(enabled = true, options?) → Promise<{}>. It keeps the screen on while the app is visible (FLAG_KEEP_SCREEN_ON); keepAwake(false) lets it turn off again.

import { screen } from "/__koru/core.mjs";
await screen.keepAwake(); // e.g. while showing a recipe
await screen.keepAwake(false);

In a browser it uses the Screen Wake Lock API when it exists; otherwise it rejects with UNAVAILABLE.

Signature: clipboard.writeText(text: string, options?) → Promise<{}>; clipboard.readText(options?) → Promise<string | null>, which is null when the clipboard is empty.

import { clipboard } from "/__koru/core.mjs";
await clipboard.writeText("hello");
const text = await clipboard.readText(); // "hello", or null if empty

From Android 10 only the app in the foreground can read the clipboard. In a browser it uses navigator.clipboard, which may ask for permission or reject with UNAVAILABLE.

Signature: invoke(method: string, params = {}, options = {}) → Promise<object>. It is the exported function in /__koru/core.mjs; window.Koru.invoke is the equivalent global. The method is a string such as "device.info"; params must be a JSON-serializable plain object. Use this for a custom plugin or when you need the unwrapped native result.

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 is string or null

options.timeout is a finite number of milliseconds from 1 to 120,000; default 10,000. The timer also covers waiting for the native channel. options.signal accepts an AbortSignal; a cancelled request rejects with CANCELLED. Cancellation prevents an unsent request, but cannot undo a native action already dispatched. At most 256 calls can be pending. A request's serialized JSON must stay below 65,536 characters.

Result: the native result object. Built-in action methods return {}; the wrapper storage.get() converts the raw { value } result into a string or null. Custom handlers define their own result object.