defmodule Counterpoint.Queue do
  @moduledoc """
  Behaviour for enqueueing automation jobs triggered by events.

  Implement this behaviour to connect Counterpoint automations to a background
  job system (e.g. Oban).  The implementation receives an automation module
  and the triggering envelope, and is responsible for scheduling the job.

  See `Counterpoint.Automation` for how automations consume enqueued jobs.
  """

  @doc """
  Enqueue a job for `automation_module` triggered by `envelope`.

  Return `{:ok, job}` on success or `{:error, reason}` on failure.
  """
  @callback enqueue(automation_module :: module(), envelope :: Counterpoint.Envelope.t()) ::
              {:ok, term()} | {:error, term()}
end