-spec advertise(client(), procedure(), fun()) -> {ok, reference()} | {error, term()}.

Advertise an RPC procedure handler.

-spec advertise(client(), procedure(), fun(), map()) -> {ok, reference()} | {error, term()}.

Advertise with options.

-spec call(client(), procedure(), term()) -> {ok, term()} | {error, term()}.

Call a remote procedure (default 5s timeout).

-spec call(client(), procedure(), term(), pos_integer()) -> {ok, term()} | {error, term()}.

Call a remote procedure with timeout.

-spec call_node(client(), binary(), procedure(), term()) -> {ok, term()} | {error, term()}.

Call a remote procedure on a specific target node (default 5s timeout).

Target can be a mesh name, site_id, or node_id (all binaries). The relay resolves the target and routes the CALL directly to that node.

-spec call_node(client(), binary(), procedure(), term(), pos_integer()) ->
                   {ok, term()} | {error, term()}.

Call a remote procedure on a specific target node with timeout.

-spec connect(binary() | [binary()], map()) -> {ok, client()} | {error, term()}.

Connect to a Macula relay.

Returns a client PID (macula_mesh_client gen_server) that you pass to all other API functions. Accepts a single URL binary or a list.

-spec disconnect(client()) -> ok.

Disconnect from the relay.

-spec ensure_distributed() -> ok | {error, term()}.

Ensure this node is running in distributed mode.

-spec get_cookie() -> atom().

Get the Erlang cluster cookie.

-spec join_mesh(map()) -> ok | {error, term()}.

Join the Macula relay mesh with Erlang distribution.

After calling this, standard OTP distribution works across firewalls. Options: relays (required list), realm, identity, site, tls_verify.

-spec list_nodes(client()) -> {ok, map()} | {error, term()}.

List all nodes connected to the relay (default 5s timeout).

-spec list_nodes(client(), map()) -> {ok, map()} | {error, term()}.

List all nodes connected to the relay with options.

-spec monitor_nodes() -> ok.

Subscribe to node up/down events.

-spec publish(client(), topic(), term()) -> ok.

Publish an event to a topic (fire-and-forget).

-spec publish(client(), topic(), term(), map()) -> ok.

Publish an event with options.

-spec resolve(client(), binary()) -> {ok, map()} | {error, term()}.

Resolve a mesh name to node identity information.

Returns the node's identity including name, site_id, city, endpoint, and connected_at timestamp. Works for names, site_ids, or node_ids.

-spec set_cookie(atom() | binary()) -> ok.

Set the Erlang cluster cookie.

-spec subscribe(client(), topic(), fun((term()) -> ok) | pid()) -> {ok, reference()} | {error, term()}.

Subscribe to a topic.

The callback receives the event payload (map or binary). Returns a subscription reference for unsubscribing.

-spec unadvertise(client(), procedure()) -> ok | {error, term()}.

Stop advertising a procedure.

-spec unmonitor_nodes() -> ok.

Unsubscribe from node up/down events.

-spec unsubscribe(client(), reference()) -> ok | {error, term()}.

Unsubscribe from a topic.