meradomo-engine 0.2.1

# meradomo-engine

The Rust SDK for embedding the **[Meradomo](https://meradomo.com) engine** in your
app — so your users get a public web address for their local app with **one
download, not two**.

This crate is the open-source **launcher/client**: it discovers a running engine,
spawns one from a bundled payload, attaches to a shared engine, and publishes your
app — all over the engine's loopback HTTP protocol. The engine binary itself is a
separate, pre-built download (see below).

```toml
[dependencies]
meradomo-engine = "0.2"
```

## Quick start

```rust
use meradomo_engine::{connect, ConnectRequest, EngineConfig};
use std::time::Duration;

let req = ConnectRequest {
    control_plane: "https://account.meradomo.com",
    app_id: "com.example.myapp",   // your app id (also its first-party id)
    publish_name: "music",         // → music.<name>.meradomo.com
    publish_label: "Music",
    local_port: 3000,              // where your app is listening
    poll_timeout: Duration::from_secs(5 * 60),
};

let connected = connect(
    &req,
    std::process::id(),
    |url| open_in_browser(url),                 // send the user to sign in / pay
    |token, host| save_credential(token, host), // persist for next launch
    |token| EngineConfig { /* bundled node/frpc/agent.mjs paths … */ ..cfg(token) },
)?;

println!("Live at {}", connected.publish.url.unwrap_or_default());
```

On the next launch, reuse the saved credential and call
[`spawn_or_attach`](https://docs.rs/meradomo-engine) — no browser. See the worked
example in [`examples/hello_meradomo.rs`](examples/hello_meradomo.rs).

## The engine bundle (closed, pre-built)

The engine binary (`agent.mjs` + a pinned Node runtime + the outbound client) is
the Meradomo product and ships as a **versioned, checksummed download**, indexed by
a public manifest:

```
https://stmeraqqemciyamqs2e.blob.core.windows.net/releases/engine-sdk/manifest.json
```

Fetch the manifest, download `bundle.url`, verify `bundle.sha256`, and drop the
`sidecars/` + `resources/` into your app's bundle (Tauri `externalBin` +
`resources`). The manifest also carries the wire `protocol` version — attach to an
incumbent engine only when its protocol matches [`ENGINE_PROTOCOL`].

## Sharing it with other people

An app can hand its own users access, without sending them to a browser or asking
them to install anything of Meradomo's:

```rust
use meradomo_engine::{invite, people, revoke};

// Everyone who can reach this computer, and the apps that can be shared.
let listed = people(mgmt_base)?;
for person in &listed.members {
    println!("{} — {} ({})", person.email, person.status, person.apps.join(", "));
}

// Invite somebody, handing over one app in the same step. They get an email
// naming that app and its address, and it is reachable the moment they accept.
invite(mgmt_base, "them@example.com", &["Music".to_string()])?;

// Withdraw one app, or remove them from the computer entirely.
revoke(mgmt_base, &person.account_id)?;
```

**Where the authority comes from.** Not your process — the engine holds the
computer's credential and lends it to an app that has registered with it.
[`register`] collects that capability, so call it (or `spawn_or_attach`, which
does) before any of the above; the calls return [`PeopleError::NotAttached`]
otherwise. The capability is minted per engine **run** and lives only in memory,
so registering again after an engine restart is how you get a fresh one —
`register` is idempotent and safe to call before each request.

Every rule stays with Meradomo: what counts as an address, which apps may be
granted, and how often invitations may be sent. Its refusals arrive as
[`PeopleError::Refused`] carrying the exact message, which is written to be shown
to a person — so show it rather than replacing it with something of your own.

## The three integration paths

1. **Detect the Meradomo app** (no bundle) — the plain [Agent API](https://developers.meradomo.com/guides/agent-api).
2. **Embed the engine, Model A** — the user pays Meradomo; **one download**. This crate.
3. **Embed the engine, Model B** — you pay Meradomo for usage; your users need no Meradomo account. *Coming soon.*

Full docs: **https://developers.meradomo.com/guides/embedded-engine**

## License

MIT.