# `JoobQ`
[🔗](https://github.com/azutoolkit/joobqui/tree/master/sdks/elixir/blob/main/lib/joobq.ex#L2)

A producer client for the JoobQ SDK gateway (`/api/v1/sdk`) of a self-hosted JoobQUI server.

JoobQUI version 0.8.0; an SDK talks to a server of its own version or later.

Start an instance in the application's supervision tree (options: `JoobQ.Config`):

    children = [{JoobQ, url: "https://joobqui.example.com", token: System.fetch_env!("JOOBQ_SDK_TOKEN")}]

Calls answer `{:ok, answer}` or `{:error, %JoobQ.Error{}}`; their `!` variants answer the answer or raise the error.
A 426 (the gateway refuses this SDK's version) answers `{:error, %JoobQ.SdkTooOldError{}}` instead, and is never
sent again: an instance whose worker meets it logs the server's message and stops at once (no drain, no
deregistration) with the exit `{:shutdown, %JoobQ.SdkTooOldError{}}`, which its supervisor gets.

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

The child specification of an instance: `{JoobQ, opts}` in a supervisor (see `JoobQ.Config`).

# `create_batch`

```elixir
@spec create_batch([tuple()], keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Creates a JoobQ Pro batch of `jobs` with its callbacks (`POST /sdk/batches`, see `JoobQ.Batches`):
`{:ok, %{"batch_id", "total", "jobs"}}`. Sent once: a `:transport` error MAY mean the batch was created.
`opts`: the batch's and `:name`, the instance.

# `describe_workflow`

```elixir
@spec describe_workflow(String.t(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

A workflow run (JoobQ Pro): `JoobQ.Workflows.describe/2`.

# `enqueue`

```elixir
@spec enqueue(String.t(), String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Enqueues a job of `job_type` on `queue` with `POST /sdk/jobs`, answering once the job is stored:
`{:ok, %{"jid" => jid, "queue" => queue, "status" => status}}`. `opts` are the job's (`JoobQ.Job`) and `:name`,
the instance (`JoobQ` by default). A `:transport` or `:bad_response` error MAY mean the job is stored (see
`JoobQ.Error`): give it a `unique_key` before sending it again.

# `enqueue!`

```elixir
@spec enqueue!(String.t(), String.t(), term(), keyword()) :: map()
```

`enqueue/4`, answering the stored job or raising `JoobQ.Error`.

# `enqueue_all`

```elixir
@spec enqueue_all([tuple()], keyword()) ::
  {:ok, [map()]} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

`enqueue_many/2` under the name Oban users know.

# `enqueue_async`

```elixir
@spec enqueue_async(String.t(), String.t(), term(), keyword()) :: Task.t()
```

`enqueue/4` without waiting: answers a `Task` whose `Task.await/2` gives what `enqueue/4` answers. A wrong option,
a payload Jason cannot encode (`JoobQ.Error`) or an instance that is not started raises here, before the task starts.

# `enqueue_many`

```elixir
@spec enqueue_many([tuple()], keyword()) ::
  {:ok, [map()]} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Enqueues `jobs` with `POST /sdk/jobs/batch`, 500 per call (see `JoobQ.Job.batches/2` for a job's shapes), and
answers one `%{"jid", "queue", "status"}` per job, in order. `opts`: `:name`, and `:context`, the context of every
job without its own. The calls are made one after the other; when one fails its error is the answer, and the jobs
of the calls before it stay stored: they are the error's `details.stored` (the gateway's own details, if any, are
then `details.gateway`).

# `enqueue_many!`

```elixir
@spec enqueue_many!([tuple()], keyword()) :: [map()]
```

`enqueue_many/2`, answering the stored jobs or raising `JoobQ.Error`.

# `get_batch`

```elixir
@spec get_batch(String.t(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

The progress of the batch `id` (`GET /sdk/batches/:id`, JoobQ Pro): `{:ok, %{"status", "total", "pending",
"succeeded", "failed", ...}}`. An id that is not a UUID raises `ArgumentError`; an unknown one answers 404.
`opts`: `:name`, the instance.

# `query_workflow`

```elixir
@spec query_workflow(String.t(), String.t(), keyword()) ::
  {:ok, term()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Answers a workflow run's query (JoobQ Pro): `JoobQ.Workflows.query/3`.

# `rate_limit`

```elixir
@spec rate_limit(String.t(), pos_integer(), pos_integer(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Reserves a slot of the rate limit `key`, `limit` per `period_ms` (`POST /sdk/rate-limit`, JoobQ Pro; see
`JoobQ.RateLimits`): `{:ok, %{"allowed" => boolean, "retry_after_ms" => ms}}`. `opts`: `:name`, the instance.

# `register_schedule`

```elixir
@spec register_schedule(String.t(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Registers, or updates, the job schedule `name` (`POST /sdk/schedules`): `{:ok, %{"id", "name", "kind", "created"}}`.
`opts` are the schedule's (`JoobQ.Schedules`: `:cron` or `:every`, ...) and `:name`, the instance.

# `sdk_version`

```elixir
@spec sdk_version() :: String.t()
```

The SDK's version, the JoobQUI release it was generated from.

# `signal_workflow`

```elixir
@spec signal_workflow(String.t(), String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Sends a signal to a workflow run (JoobQ Pro): `JoobQ.Workflows.signal/4`.

# `start_link`

```elixir
@spec start_link(keyword()) :: Supervisor.on_start()
```

Starts an instance outside a supervision tree (see `JoobQ.Config`).

# `start_workflow`

```elixir
@spec start_workflow(String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Starts a workflow run (JoobQ Pro): `JoobQ.Workflows.start/3`.

# `update_workflow`

```elixir
@spec update_workflow(String.t(), String.t(), term(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Sends an update to a workflow run (JoobQ Pro): `JoobQ.Workflows.update/4`.

# `upsert_workflow_attributes`

```elixir
@spec upsert_workflow_attributes(String.t(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

Sets and removes a workflow run's search attributes (JoobQ Pro): `JoobQ.Workflows.upsert_attributes/2`.

# `workflow_history`

```elixir
@spec workflow_history(String.t(), keyword()) ::
  {:ok, [map()]} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

A workflow run's events (JoobQ Pro): `JoobQ.Workflows.history/2`.

# `workflow_result`

```elixir
@spec workflow_result(String.t(), keyword()) ::
  {:ok, map()} | {:error, JoobQ.Error.t() | JoobQ.SdkTooOldError.t()}
```

A workflow run once closed (JoobQ Pro): `JoobQ.Workflows.result/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
