import type { RuntimePlatform } from "../app-info";

// Why a device feature may not be usable; each status has its own message in capability-gate.tsx.
export type CapabilityStatus =
    /** Ready to use. */
    | "available"
    /** Supported, but the user has not been asked yet. */
    | "needs-permission"
    /** The user refused; only system settings can change that now. */
    | "permission-denied"
    /** A system component it depends on is missing (e.g. Health Connect). */
    | "needs-install"
    /** This app build predates the feature's native code: update the app. */
    | "needs-app-update"
    /** This phone cannot do it (OS too old, missing hardware). */
    | "unsupported-device"
    /** Not on this platform at all -- on web, typically: "use the app". */
    | "unsupported-platform"
    /** Checking failed; worth retrying. */
    | "error";

export interface CapabilityState {
    status: CapabilityStatus;
    /** needs-install: where to get the missing component. */
    installUrl?: string;
    /** needs-install: its name, for the message («Health Connect»). */
    installName?: string;
}

export interface Capability {
    id: string;
    /** What the user would lose, in Persian, for fallback messages. */
    title: string;
    /** Where it can exist. Everywhere else is unsupported-platform, without asking. */
    platforms: RuntimePlatform[];
    /** Capacitor plugins the app must contain; without them it is an older build (needs-app-update). */
    requiresPlugins?: string[];
    /** Finer check once platform and plugins are satisfied. Default: available. */
    probe?(): Promise<CapabilityState>;
    /** Ask the OS for permission after needs-permission. Resolves to the new state. */
    request?(): Promise<CapabilityState>;
}
