defmodule TribeOne.TribesPlugin.Aether.Chat.Backend do
  @moduledoc """
  Behaviour for chat storage/transport backends.

  Backends are plain Elixir modules. Ash resources store conversation projections,
  participants, and local message state, while protocol backends may use Parrhesia
  raw events as canonical storage.

  `opts` may carry signing/client context for future non-custodial clients, e.g.
  browser-held Nostr signers, NIP-07 bridges, or server-session signers. Backends
  that need signatures should reject missing signer context explicitly instead of
  assuming server-side custody.
  """

  alias TribeOne.TribesPlugin.Aether.Chat.Channel

  @type attrs :: map()
  @type opts :: keyword()

  @callback capabilities() :: map()
  @callback ensure_conversation(attrs(), opts()) :: {:ok, Channel.t()} | {:error, term()}
  @callback list_messages(Channel.t(), opts()) :: {:ok, [struct()]} | {:error, term()}
  @callback send_message(Channel.t(), attrs(), opts()) :: {:ok, struct()} | {:error, term()}
  @callback subscribe(Channel.t(), pid(), opts()) :: :ok | {:error, term()}
end