@spec api_paginate(:twitch | :youtube | :kick, String.t(), map(), keyword()) ::
  {:ok, [map()]} | {:error, term()}

Collects paginated API responses using one function for all platforms.

Twitch and YouTube use built-in cursor/page-token extractors. Kick and custom endpoints can pass next: fn decoded_body -> next_params_or_nil end.

@spec api_request(:twitch | :youtube | :kick, atom(), String.t(), map(), keyword()) ::
  GelotvBot.HTTPClient.response()

Sends a raw request to a platform API using one unified function.

GelotvBot.api_request(:twitch, :get, "/streams", credentials,
  params: [user_login: "gelotv"]
)

Use this when you need an endpoint that does not have a typed helper yet.

@spec api_request_decoded(
  :twitch | :youtube | :kick,
  atom(),
  String.t(),
  map(),
  keyword()
) ::
  {:ok, map()} | {:error, term()}

Sends a platform API request and returns the decoded JSON body.

The response keeps raw :status, :headers, and :body fields and adds :decoded_body for successful JSON responses.

@spec broadcast(
  [GelotvBot.Target.t()],
  GelotvBot.Message.t() | GelotvBot.Command.t() | String.t(),
  keyword()
) :: [send_result()]

Sends a message directly to a list of targets without starting a named bot.

@spec broadcast_live(
  [GelotvBot.LiveDiscovery.spec()],
  message_input_or_many(),
  keyword()
) :: {:ok, [send_result()]} | {:error, term()}

Discovers active live targets and sends multiple messages to all of them.

@spec broadcast_many(
  [GelotvBot.Target.t()],
  [GelotvBot.Message.t() | GelotvBot.Command.t() | String.t()],
  keyword()
) :: [send_result()]

Sends multiple messages/commands directly to all targets.

@spec discover_live_targets(
  [GelotvBot.LiveDiscovery.spec()],
  keyword()
) :: {:ok, [GelotvBot.Target.t()]} | {:error, term()}

Discovers active live targets for one or more platform specs.

@spec dispatch(target_input_or_many(), message_input_or_many(), keyword()) :: [
  send_result()
]

Dispatches one or many messages to one or many targets with one direct call.

This is the most compact path for applications that do not want to manage a named bot process. A single target/message and a list of targets/messages use the same function.

@spec list_bots() :: [term()]

Lists currently running supervised bot instance names.

@spec put_targets(term(), [GelotvBot.Target.t()]) :: :ok | {:error, term()}

Replaces the target list for a named supervised bot instance.

@spec send(
  term(),
  GelotvBot.Message.t() | GelotvBot.Command.t() | String.t(),
  keyword()
) :: [
  send_result()
]

Broadcasts a message through a named supervised bot instance.

@spec send_live([GelotvBot.LiveDiscovery.spec()], message_input_or_many(), keyword()) ::
  {:ok, [send_result()]} | {:error, term()}

Alias for broadcast_live/3 for callers that prefer send-oriented naming.

@spec send_many(
  term(),
  [GelotvBot.Message.t() | GelotvBot.Command.t() | String.t()],
  keyword()
) :: [
  send_result()
]

Broadcasts multiple messages/commands through a named supervised bot instance.

@spec start_bot(
  term(),
  keyword()
) :: DynamicSupervisor.on_start_child()

Starts a supervised bot instance.

{:ok, _pid} =
  GelotvBot.start_bot(:alerts,
    targets: [
      %GelotvBot.Target{
        platform: :twitch,
        channel: "gelotv",
        adapter: MyApp.TwitchAdapter
      }
    ]
  )

@spec stop_bot(term()) :: :ok | {:error, :not_found}

Stops a supervised bot instance by name.

@spec targets(term()) :: [GelotvBot.Target.t()]

Returns the target list for a named supervised bot instance.

@spec token(
  :twitch | :youtube | :kick,
  :client_credentials | :refresh,
  map(),
  keyword()
) ::
  {:ok, map()} | {:error, term()}

Requests an OAuth token using one function for supported platform helpers.