Guide · v0.13.8

Platform APIs

Deep links, file associations, notifications, permissions, the share sheet, location and biometrics, with one shape on every OS: where a platform has no equivalent the answer is { supported: false }, never an exception.

Declare the URL schemes and file types the app opens, then listen for them. A listener receives the links or files the app was launched with right after it registers, then those of later launches that requestSingleInstance forwards; call it before createApp and no other wiring is needed.

app.tsx
import { createApp, requestSingleInstance } from "@tarve/core";

const instance = await requestSingleInstance({ schemes: ["notes"] });
if (!instance.primary) process.exit(0);

const app = createApp(App, {
  protocols: ["notes"],
  fileTypes: [{ ext: "note", name: "Note", icon: "note.png" }],
});

app.onOpenUrl((url, event) => openLink(url));        // notes://…
app.onOpenFiles((files, event) => files.forEach(open)); // absolute paths
// event: { initial, args, cwd }; both return an unsubscribe function

Packages register them for you: put tarve.protocols and tarve.fileTypes in package.json (or pass --protocol and --file-type ext=Name) and tarve package writes HKCU/MSIX entries on Windows, MimeType and shared-mime-info on Linux, and intent filters on Android. At run time, registerProtocol / registerFileType (and their unregister* counterparts) register for the current user without admin rights. On Android a shared content:// document is copied into the app's cache and delivered as a path. See also Desktop integration.

Notifications

app.notify needs no tray icon. A click brings the window forward and runs that notification's onClick.

app.tsx
app.notify({ title: "Export finished", body: "report.pdf is ready", onClick: () => openReport() });
PlatformShown through
WindowsA toast under appIdentity (or tarve.appId); without one Tarve registers Tarve.<window title> for the current user. Falls back to the tray balloon when a toast cannot show.
Linuxorg.freedesktop.Notifications (GNOME, KDE, dunst, mako…).
AndroidThe notification shade; asks for POST_NOTIFICATIONS first on Android 13+. Set tarve.android.notificationIcon to replace the white bell.

Permissions

app.tsx
const states = await app.requestPermissions(["CAMERA", "RECORD_AUDIO"]); // { CAMERA: "granted", RECORD_AUDIO: "denied" }
const now = await app.checkPermissions(["CAMERA"]);                     // "granted" | "prompt" | "denied", no dialog

On Android, requestPermissions shows the system prompt and resolves once the user answers; a permission missing from the manifest is denied at once. Desktops have no per-app prompt and report every name as "granted".

Android also blocks plain http:// by default, media playback included; set tarve.android.cleartextTraffic: true in package.json for an app that must reach an http:// server (a media server on the LAN).

Share, location and biometrics

app.tsx
await app.share({ title: "Report", text: "Q3 numbers", url: "https://example.com", files: ["out/report.pdf"] });

const fix = await app.getCurrentPosition({ highAccuracy: true, timeoutMs: 10_000 });
if (fix.position) show(fix.position.latitude, fix.position.longitude);
else console.warn(fix.code); // "unsupported" | "denied" | "unavailable" | "timeout"

const stop = app.watchPosition(result => update(result)); // about every second

const auth = await app.authenticate({ reason: "Unlock your vault" });
if (auth.success) unlock(); // else auth.code: "not-enrolled" | "canceled" | "failed" | "lockout" | "busy"
APIAndroidWindowsLinux
shareSystem chooser; files go through a private read-only provider.The Windows share UI.supported: false
getCurrentPosition / watchPositionLocationManager (no Play Services). Declare ACCESS_FINE_LOCATION / ACCESS_COARSE_LOCATION yourself.Geolocator.supported: false
authenticateBiometricPrompt, with the device PIN as fallback (API 28+).Windows Hello.supported: false

Location asks for the permission before the first fix. On Android, app.webSignIn({ url, cookieUrl, cookies }) opens a sign-in page in the system WebView and resolves with the cookies of cookieUrl once the user is signed in. Push notifications (FCM/APNs) are not available yet.