@marinoscar/platform-web 0.0.0-stage → 0.1.0-next.4

package/dist/android-app/headless/hooks.d.ts

@@ -0,0 +1,70 @@
+import type { AndroidAppResponse, PublicRelease, TrustedAndroidApp } from '@marinoscar/platform-contract/android-app';
+import { type AndroidAppClient } from './client.js';
+/**
+ * The android-app client over the host's transport (`PlatformHostProvider`).
+ *
+ * @returns a memoised client.
+ *
+ * @stability experimental
+ */
+export declare function useAndroidAppClient(): AndroidAppClient;
+/**
+ * What {@link useAndroidRelease} returns.
+ *
+ * @stability experimental
+ */
+export interface UseAndroidReleaseReturn {
+    /** The current release, or null (none published, not loaded, disabled or failed). */
+    release: PublicRelease | null;
+    /** Whether the request is in flight. */
+    isLoading: boolean;
+    /** The error message, or null (a 404 NO_RELEASE is not an error). */
+    error: string | null;
+}
+/**
+ * The release this server offers, for any signed-in user. Requests nothing
+ * while `enabled` is false (the update banner passes `false` outside the
+ * TWA, so an ordinary tab makes no request).
+ *
+ * @param enabled - whether to fetch (default true).
+ * @returns the release state.
+ *
+ * @example
+ * ```tsx
+ * const { release } = useAndroidRelease(getInstalledAppVersion() !== null);
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function useAndroidRelease(enabled?: boolean): UseAndroidReleaseReturn;
+/**
+ * What {@link useAndroidAppConfig} returns.
+ *
+ * @stability experimental
+ */
+export interface UseAndroidAppConfigReturn {
+    /** The admin view, or null until loaded. */
+    config: AndroidAppResponse | null;
+    /** Loading the first time. */
+    isLoading: boolean;
+    /** A load error. */
+    error: string | null;
+    /** A save in flight. */
+    isSaving: boolean;
+    /** The last save's error (the server's message, typed reason included). */
+    saveError: string | null;
+    /** Replaces the trusted list; resolves whether it saved. */
+    save(trustedApps: TrustedAndroidApp[]): Promise<boolean>;
+    /** Reloads the view. */
+    refresh(): Promise<void>;
+}
+/**
+ * The admin view of `/api/admin/android-app` with save and refresh.
+ *
+ * @returns the state and actions.
+ *
+ * @stability experimental
+ */
+export declare function useAndroidAppConfig(): UseAndroidAppConfigReturn;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/android-app/headless/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/android-app/headless/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAGtH,OAAO,EAA0B,KAAK,gBAAgB,EAA4B,MAAM,aAAa,CAAC;AAOtG;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAGtD;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,qFAAqF;IACrF,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,UAAO,GAAG,uBAAuB,CAuBzE;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,4CAA4C;IAC5C,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC,8BAA8B;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,oBAAoB;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,wBAAwB;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4DAA4D;IAC5D,IAAI,CAAC,WAAW,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,wBAAwB;IACxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,yBAAyB,CAyC/D"}

package/dist/android-app/headless/hooks.js

@@ -0,0 +1,104 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { isPlatformApiError, usePlatformApi } from '../../core/index.js';
+import { createAndroidAppClient } from './client.js';
+function messageOf(error) {
+    if (isPlatformApiError(error))
+        return error.message;
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The android-app client over the host's transport (`PlatformHostProvider`).
+ *
+ * @returns a memoised client.
+ *
+ * @stability experimental
+ */
+export function useAndroidAppClient() {
+    const api = usePlatformApi();
+    return useMemo(() => createAndroidAppClient(api), [api]);
+}
+/**
+ * The release this server offers, for any signed-in user. Requests nothing
+ * while `enabled` is false (the update banner passes `false` outside the
+ * TWA, so an ordinary tab makes no request).
+ *
+ * @param enabled - whether to fetch (default true).
+ * @returns the release state.
+ *
+ * @example
+ * ```tsx
+ * const { release } = useAndroidRelease(getInstalledAppVersion() !== null);
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function useAndroidRelease(enabled = true) {
+    const client = useAndroidAppClient();
+    const [state, setState] = useState({ release: null, isLoading: enabled, error: null });
+    useEffect(() => {
+        if (!enabled) {
+            setState({ release: null, isLoading: false, error: null });
+            return;
+        }
+        let cancelled = false;
+        setState((previous) => ({ ...previous, isLoading: true }));
+        client.latest().then((release) => !cancelled && setState({ release, isLoading: false, error: null }), (error) => {
+            if (cancelled)
+                return;
+            const notFound = isPlatformApiError(error) && error.status === 404;
+            setState({ release: null, isLoading: false, error: notFound ? null : messageOf(error) });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, enabled]);
+    return state;
+}
+/**
+ * The admin view of `/api/admin/android-app` with save and refresh.
+ *
+ * @returns the state and actions.
+ *
+ * @stability experimental
+ */
+export function useAndroidAppConfig() {
+    const client = useAndroidAppClient();
+    const [config, setConfig] = useState(null);
+    const [isLoading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [isSaving, setSaving] = useState(false);
+    const [saveError, setSaveError] = useState(null);
+    const refresh = useCallback(async () => {
+        try {
+            setConfig(await client.get());
+            setError(null);
+        }
+        catch (e) {
+            setError(messageOf(e));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    const save = useCallback(async (trustedApps) => {
+        setSaving(true);
+        setSaveError(null);
+        try {
+            setConfig(await client.replace(trustedApps));
+            return true;
+        }
+        catch (e) {
+            setSaveError(messageOf(e));
+            return false;
+        }
+        finally {
+            setSaving(false);
+        }
+    }, [client]);
+    return { config, isLoading, error, isSaving, saveError, save, refresh };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/android-app/headless/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/android-app/headless/hooks.ts"],"names":[],"mappings":"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"}

package/dist/android-app/headless/identity.d.ts

@@ -0,0 +1,20 @@
+import type { AndroidIdentity, AndroidIdentitySource } from '@marinoscar/platform-contract/android-app';
+/**
+ * Resolves the Android app's identity from `packages/shared/identity.json`
+ * (and its optional `android` block): the application id (the default
+ * trusted package), the deep-link scheme, the on-device storage prefix and
+ * the APK stem. The same rule the Gradle build applies.
+ *
+ * @param identity - `ANDROID_IDENTITY_SOURCE` of `@app/shared`, or the same shape.
+ * @returns the resolved identity.
+ *
+ * @example
+ * ```ts
+ * const { applicationId, apkStem } = androidIdentity(ANDROID_IDENTITY_SOURCE);
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function androidIdentity(identity: AndroidIdentitySource): AndroidIdentity;
+//# sourceMappingURL=identity.d.ts.map

package/dist/android-app/headless/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../src/android-app/headless/identity.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAExG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,qBAAqB,GAAG,eAAe,CAEhF"}

package/dist/android-app/headless/identity.js

@@ -0,0 +1,24 @@
+// The Android identity, re-exported for the web (#746): one derivation for
+// the API, the web, the CLI and (in Kotlin) the Gradle build.
+import { androidIdentity as contractAndroidIdentity } from '@marinoscar/platform-contract/android-app';
+/**
+ * Resolves the Android app's identity from `packages/shared/identity.json`
+ * (and its optional `android` block): the application id (the default
+ * trusted package), the deep-link scheme, the on-device storage prefix and
+ * the APK stem. The same rule the Gradle build applies.
+ *
+ * @param identity - `ANDROID_IDENTITY_SOURCE` of `@app/shared`, or the same shape.
+ * @returns the resolved identity.
+ *
+ * @example
+ * ```ts
+ * const { applicationId, apkStem } = androidIdentity(ANDROID_IDENTITY_SOURCE);
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function androidIdentity(identity) {
+    return contractAndroidIdentity(identity);
+}
+//# sourceMappingURL=identity.js.map

package/dist/android-app/headless/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../src/android-app/headless/identity.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8DAA8D;AAE9D,OAAO,EAAE,eAAe,IAAI,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AAGvG;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,QAA+B;IAC7D,OAAO,uBAAuB,CAAC,QAAQ,CAAC,CAAC;AAC3C,CAAC"}

package/dist/android-app/headless/index.d.ts

@@ -0,0 +1,9 @@
+export type { AdminRelease, AndroidAppResponse, AndroidAppTestNotificationResponse, AndroidIdentity, AndroidIdentitySource, DownloadLink, PublicRelease, ReportedAndroidApp, TrustedAndroidApp, } from '@marinoscar/platform-contract/android-app';
+export { androidIdentity } from './identity.js';
+export { DEFAULT_TWA_KEY_PREFIX, captureTwaLaunch, getInstalledAppVersion, isRunningInTwa, twaSessionKeys } from './twa.js';
+export type { InstalledAppVersion, TwaSessionKeys } from './twa.js';
+export { createAndroidAppClient } from './client.js';
+export type { AndroidAppClient, AndroidAppTransport, AndroidReleaseUploadInput } from './client.js';
+export { useAndroidAppClient, useAndroidAppConfig, useAndroidRelease } from './hooks.js';
+export type { UseAndroidAppConfigReturn, UseAndroidReleaseReturn } from './hooks.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/android-app/headless/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/android-app/headless/index.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,kCAAkC,EAClC,eAAe,EACf,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC5H,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACzF,YAAY,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/android-app/headless/index.js

@@ -0,0 +1,9 @@
+// `@marinoscar/platform-web/android-app/headless`: the Android companion's
+// web logic with no component (issue #746): the TWA launch helpers, the API
+// client, the hooks and the shared Android identity. Documented in
+// ../README.md.
+export { androidIdentity } from './identity.js';
+export { DEFAULT_TWA_KEY_PREFIX, captureTwaLaunch, getInstalledAppVersion, isRunningInTwa, twaSessionKeys } from './twa.js';
+export { createAndroidAppClient } from './client.js';
+export { useAndroidAppClient, useAndroidAppConfig, useAndroidRelease } from './hooks.js';
+//# sourceMappingURL=index.js.map

package/dist/android-app/headless/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/android-app/headless/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAC5E,mEAAmE;AACnE,gBAAgB;AAahB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE5H,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/android-app/headless/twa.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The default prefix of the `sessionStorage` keys (`<prefix>.twa`, ...). An
+ * app passes its identity's `storagePrefix` when two apps share an origin.
+ *
+ * @stability experimental
+ */
+export declare const DEFAULT_TWA_KEY_PREFIX = "android";
+/**
+ * The installed Android build, as its TWA launch URL reported it.
+ *
+ * @stability experimental
+ */
+export interface InstalledAppVersion {
+    /** `appVersion`, or null when the launch did not carry it. */
+    versionName: string | null;
+    /** `appVersionCode`. */
+    versionCode: number;
+}
+/**
+ * The `sessionStorage` keys the launch flags live under.
+ *
+ * @stability experimental
+ */
+export interface TwaSessionKeys {
+    /** `1` when the session started from the Android app. */
+    launched: string;
+    /** The installed `versionName`. */
+    versionName: string;
+    /** The installed `versionCode`. */
+    versionCode: string;
+}
+/**
+ * The three `sessionStorage` keys of a prefix.
+ *
+ * @param prefix - the key prefix.
+ * @returns the keys.
+ *
+ * @stability experimental
+ */
+export declare function twaSessionKeys(prefix?: string): TwaSessionKeys;
+/**
+ * Remembers a `?source=twa` launch, and the installed build it names, for
+ * the rest of the session. Call once, before the router drops the query
+ * string. Safe to call more than once; never throws (blocked storage falls
+ * back to the referrer check).
+ *
+ * @param search - the launch query string (default `window.location.search`).
+ * @param prefix - the key prefix (default {@link DEFAULT_TWA_KEY_PREFIX}).
+ *
+ * @example
+ * ```ts
+ * // apps/web/src/main.tsx, before ReactDOM.createRoot
+ * captureTwaLaunch();
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export declare function captureTwaLaunch(search?: string, prefix?: string): void;
+/**
+ * True inside the Android app's TWA: the flag `captureTwaLaunch` saved, or an
+ * `android-app://` referrer.
+ *
+ * @param prefix - the key prefix.
+ * @returns whether this page runs in the TWA.
+ *
+ * @stability experimental
+ */
+export declare function isRunningInTwa(prefix?: string): boolean;
+/**
+ * The installed build as the TWA launch URL reported it, or null outside the
+ * TWA or for a build that sends no `appVersionCode`.
+ *
+ * @param prefix - the key prefix.
+ * @returns the installed version, or null.
+ *
+ * @stability experimental
+ */
+export declare function getInstalledAppVersion(prefix?: string): InstalledAppVersion | null;
+//# sourceMappingURL=twa.d.ts.map

package/dist/android-app/headless/twa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twa.d.ts","sourceRoot":"","sources":["../../../src/android-app/headless/twa.ts"],"names":[],"mappings":"AAmBA;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAA+B,GAAG,cAAc,CAEtF;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,MAA+B,GAAG,IAAI,CAe/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,MAA+B,GAAG,OAAO,CAO/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAE,MAA+B,GAAG,mBAAmB,GAAG,IAAI,CAW1G"}

package/dist/android-app/headless/twa.js

@@ -0,0 +1,126 @@
+// =============================================================================
+// Is this page running inside the Android app's Trusted Web Activity? (#746)
+// =============================================================================
+//
+// Merged from EvoPath's and MemoriaHub's `apps/web/src/utils/twa.ts`. The
+// Kotlin `TwaLauncher` opens `<server>/?source=twa&appVersion=<name>&appVersionCode=<code>`
+// (`ServerUrls.twaLaunchUrl` of `platform-core`). The query string is gone
+// after the first in-app navigation, so `captureTwaLaunch()` runs ONCE at
+// startup (the app's `main.tsx`, before the router) and remembers it in
+// `sessionStorage`, which lives exactly as long as the TWA's browsing session.
+// A TWA also reports its referrer as `android-app://<package>`, which covers
+// a launch the flag missed.
+//
+// PRESENTATION ONLY: the answer decides whether to OFFER an update or a deep
+// link into a native screen. It grants nothing; the server never trusts it.
+// =============================================================================
+import { TWA_LAUNCH_PARAMS } from '@marinoscar/platform-contract/android-app';
+/**
+ * The default prefix of the `sessionStorage` keys (`<prefix>.twa`, ...). An
+ * app passes its identity's `storagePrefix` when two apps share an origin.
+ *
+ * @stability experimental
+ */
+export const DEFAULT_TWA_KEY_PREFIX = 'android';
+/**
+ * The three `sessionStorage` keys of a prefix.
+ *
+ * @param prefix - the key prefix.
+ * @returns the keys.
+ *
+ * @stability experimental
+ */
+export function twaSessionKeys(prefix = DEFAULT_TWA_KEY_PREFIX) {
+    return { launched: `${prefix}.twa`, versionName: `${prefix}.twa.appVersion`, versionCode: `${prefix}.twa.appVersionCode` };
+}
+function session() {
+    try {
+        return typeof window === 'undefined' ? null : window.sessionStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remembers a `?source=twa` launch, and the installed build it names, for
+ * the rest of the session. Call once, before the router drops the query
+ * string. Safe to call more than once; never throws (blocked storage falls
+ * back to the referrer check).
+ *
+ * @param search - the launch query string (default `window.location.search`).
+ * @param prefix - the key prefix (default {@link DEFAULT_TWA_KEY_PREFIX}).
+ *
+ * @example
+ * ```ts
+ * // apps/web/src/main.tsx, before ReactDOM.createRoot
+ * captureTwaLaunch();
+ * ```
+ *
+ * @extensionPoint hook
+ * @stability experimental
+ */
+export function captureTwaLaunch(search, prefix = DEFAULT_TWA_KEY_PREFIX) {
+    const store = session();
+    if (!store)
+        return;
+    try {
+        const params = new URLSearchParams(search ?? window.location.search);
+        if (params.get(TWA_LAUNCH_PARAMS.SOURCE) !== TWA_LAUNCH_PARAMS.SOURCE_VALUE)
+            return;
+        const keys = twaSessionKeys(prefix);
+        store.setItem(keys.launched, '1');
+        const name = params.get(TWA_LAUNCH_PARAMS.APP_VERSION);
+        const code = params.get(TWA_LAUNCH_PARAMS.APP_VERSION_CODE);
+        if (name)
+            store.setItem(keys.versionName, name.slice(0, 50));
+        if (code && /^\d{1,10}$/.test(code))
+            store.setItem(keys.versionCode, code);
+    }
+    catch {
+        // Storage blocked: the referrer check below still answers.
+    }
+}
+/**
+ * True inside the Android app's TWA: the flag `captureTwaLaunch` saved, or an
+ * `android-app://` referrer.
+ *
+ * @param prefix - the key prefix.
+ * @returns whether this page runs in the TWA.
+ *
+ * @stability experimental
+ */
+export function isRunningInTwa(prefix = DEFAULT_TWA_KEY_PREFIX) {
+    try {
+        if (session()?.getItem(twaSessionKeys(prefix).launched) === '1')
+            return true;
+    }
+    catch {
+        // fall through to the referrer
+    }
+    return typeof document !== 'undefined' && document.referrer.startsWith('android-app://');
+}
+/**
+ * The installed build as the TWA launch URL reported it, or null outside the
+ * TWA or for a build that sends no `appVersionCode`.
+ *
+ * @param prefix - the key prefix.
+ * @returns the installed version, or null.
+ *
+ * @stability experimental
+ */
+export function getInstalledAppVersion(prefix = DEFAULT_TWA_KEY_PREFIX) {
+    if (!isRunningInTwa(prefix))
+        return null;
+    try {
+        const store = session();
+        const keys = twaSessionKeys(prefix);
+        const code = Number(store?.getItem(keys.versionCode));
+        if (!Number.isInteger(code) || code <= 0)
+            return null;
+        return { versionName: store?.getItem(keys.versionName) ?? null, versionCode: code };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=twa.js.map

package/dist/android-app/headless/twa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twa.js","sourceRoot":"","sources":["../../../src/android-app/headless/twa.ts"],"names":[],"mappings":"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"}

package/dist/android-app/ui/AndroidAppPage.d.ts

@@ -0,0 +1,114 @@
+import { type ReactElement } from 'react';
+import type { PageSlotsBase } from '../../core/index.js';
+/**
+ * The add-form's package error.
+ *
+ * @stability experimental
+ */
+export declare const ANDROID_PACKAGE_ERROR = "Enter an Android package name, such as com.example.app.";
+/**
+ * The add-form's fingerprint error.
+ *
+ * @stability experimental
+ */
+export declare const ANDROID_SHA_ERROR = "Enter a SHA-256 fingerprint: 32 pairs of hex digits separated by colons, or 64 hex digits.";
+/**
+ * What the three sections of the Android page take.
+ *
+ * @stability experimental
+ */
+export interface AndroidAppSectionProps {
+    /** The viewer holds `system_settings:write`; without it the section's controls are disabled. */
+    canWrite: boolean;
+}
+/**
+ * The "Trusted apps" section: the apps the server vouches for in
+ * `/.well-known/assetlinks.json`, the apps devices reported, and the preview
+ * of the file. An app that composes its own Android page reuses it beside its
+ * own sections.
+ *
+ * @param props - see {@link AndroidAppSectionProps}.
+ * @returns the section body (without the page's `Paper` chrome).
+ *
+ * @example
+ * ```tsx
+ * <TrustedAppsSection canWrite={viewer.hasPermission('system_settings:write')} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function TrustedAppsSection({ canWrite }: AndroidAppSectionProps): ReactElement;
+/**
+ * The "Releases" section: the hosted APKs, the current one, and the upload.
+ *
+ * @param props - see {@link AndroidAppSectionProps}.
+ * @returns the section body (without the page's `Paper` chrome).
+ *
+ * @example
+ * ```tsx
+ * <ReleasesSection canWrite={viewer.hasPermission('system_settings:write')} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function ReleasesSection({ canWrite }: AndroidAppSectionProps): ReactElement;
+/**
+ * The "Notifications" section: subscription counts and the test notification.
+ *
+ * @param props - see {@link AndroidAppSectionProps}.
+ * @returns the section body (without the page's `Paper` chrome).
+ *
+ * @example
+ * ```tsx
+ * <NotificationsSection canWrite={viewer.hasPermission('system_settings:write')} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function NotificationsSection({ canWrite }: AndroidAppSectionProps): ReactElement;
+/**
+ * The slots of {@link AndroidAppPage}: the page-slot contract. `Sections` is
+ * drawn at both ends of the body, so an app puts its own section (a fleet
+ * dashboard, a store listing checklist) before or after the three built-in
+ * ones; {@link TrustedAppsSection}, {@link ReleasesSection} and
+ * {@link NotificationsSection} are exported for an app that composes its own page.
+ *
+ * @example
+ * ```tsx
+ * <AndroidAppPage slots={{ Sections: ({ position }) => (position === 'bottom' ? <StoreListingChecklist /> : null) }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export type AndroidAppPageSlots = PageSlotsBase;
+/**
+ * The props of {@link AndroidAppPage}.
+ *
+ * @stability experimental
+ */
+export interface AndroidAppPageProps {
+    /** Optional extension slots; omitted, the page renders exactly as it always did. */
+    slots?: AndroidAppPageSlots;
+}
+/**
+ * The admin Android app page: trusted apps, releases, test notification.
+ * Route it behind the app's `system_settings:read` gate; writes are disabled
+ * inside the page without `system_settings:write`.
+ *
+ * @param props - see {@link AndroidAppPageProps}.
+ * @returns the page.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/admin/settings/android" element={<RequirePermission permission="system_settings:read"><AndroidAppPage /></RequirePermission>} />
+ * ```
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function AndroidAppPage(props?: AndroidAppPageProps): ReactElement;
+//# sourceMappingURL=AndroidAppPage.d.ts.map

package/dist/android-app/ui/AndroidAppPage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AndroidAppPage.d.ts","sourceRoot":"","sources":["../../../src/android-app/ui/AndroidAppPage.tsx"],"names":[],"mappings":"AAmCA,OAAO,EAAoD,KAAK,YAAY,EAAE,MAAM,OAAO,CAAC;AAa5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAYzD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,4DAA4D,CAAC;AAE/F;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,+FAA+F,CAAC;AAa9H;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,gGAAgG;IAChG,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE,sBAAsB,GAAG,YAAY,CAqIrF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE,sBAAsB,GAAG,YAAY,CA+HlF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,QAAQ,EAAE,EAAE,sBAAsB,GAAG,YAAY,CA+CvF;AAaD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAE,mBAAwB,GAAG,YAAY,CAyC5E"}