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

## Deep links and file types

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.

```tsx title="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](https://tarve.dev/docs/desktop.md#single-instance).

## Notifications

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

```tsx title="app.tsx"
app.notify({ title: "Export finished", body: "report.pdf is ready", onClick: () => openReport() });
```

| Platform | Shown through |
| --- | --- |
| Windows | A 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. |
| Linux | `org.freedesktop.Notifications` (GNOME, KDE, dunst, mako…). |
| Android | The notification shade; asks for `POST_NOTIFICATIONS` first on Android 13+. Set `tarve.android.notificationIcon` to replace the white bell. |

## Permissions

```tsx title="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

```tsx title="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"
```

| API | Android | Windows | Linux |
| --- | --- | --- | --- |
| `share` | System chooser; files go through a private read-only provider. | The Windows share UI. | `supported: false` |
| `getCurrentPosition` / `watchPosition` | `LocationManager` (no Play Services). Declare `ACCESS_FINE_LOCATION` / `ACCESS_COARSE_LOCATION` yourself. | `Geolocator`. | `supported: false` |
| `authenticate` | `BiometricPrompt`, 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.

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/platform · Index for agents: https://tarve.dev/llms.txt
