package weft:app@0.1.0;

/// Host interface that a WEFT app component imports to signal lifecycle events.
interface notify {
    /// Signal to the runtime that the application has finished initialising
    /// and is ready to serve requests.  The runtime forwards this signal to
    /// the session supervisor (appd), which transitions the session to the
    /// Running state.
    ready: func();
}

/// Host interface for bidirectional IPC between the Wasm component and the
/// HTML front-end served by weft-app-shell.  Messages are JSON strings.
interface ipc {
    /// Send a payload to the HTML front-end.  Returns an error string if the
    /// channel is not connected or the write fails.
    send: func(payload: string) -> result<_, string>;

    /// Return the next pending payload from the HTML front-end, or none if
    /// no message is currently available.  Non-blocking.
    recv: func() -> option<string>;
}

/// Host interface for outbound HTTP requests.  Requires the net:fetch
/// capability to be declared in wapp.toml.
interface fetch {
    record response {
        status: u16,
        content-type: string,
        body: list<u8>,
    }

    /// Perform a synchronous HTTP request.  method is GET, POST, etc.
    /// headers is a list of (name, value) pairs.  body is the request body.
    fetch: func(
        url: string,
        method: string,
        headers: list<tuple<string, string>>,
        body: option<list<u8>>,
    ) -> result<response, string>;
}

/// Host interface for sending desktop notifications.  Requires the
/// sys:notifications capability to be declared in wapp.toml.
interface notifications {
    /// Send a desktop notification.  icon is an optional XDG icon name.
    notify: func(
        title: string,
        body: string,
        icon: option<string>,
    ) -> result<_, string>;
}

/// Host interface for reading and writing the Wayland clipboard.
/// Requires sys:clipboard:read and/or sys:clipboard:write capabilities.
interface clipboard {
    /// Return the current clipboard text contents.
    read: func() -> result<string, string>;

    /// Replace the clipboard contents with the given text.
    write: func(text: string) -> result<_, string>;
}