# `Wardrik.Orgs`

Gives each org its own settings, alongside the deployment's. See `Wardrik.OrgSettings`.

    Wardrik.start_link(name: MyApp.AgentRuntime, orgs: {MyApp.Orgs, []})

    defmodule MyApp.Orgs do
      @behaviour Wardrik.Orgs

      @impl true
      def settings(org, _config) do
        plan = MyApp.Billing.plan!(org)
        {:ok, %Wardrik.OrgSettings{ceilings: %{"plan" => [usd: plan.usd, per: :month]}}}
      end
    end

An agent's org is the first part of its ID: `acme` for `acme/@maria/assistant`.

Wardrik reads an org's settings each time one of its agents starts, wakes or is defined. To
apply new settings to awake agents, call `Wardrik.refresh/2`. Invalid settings stop the agent
from starting, with the reason.

For an org that doesn't exist, return an error:

    {:error, Wardrik.Error.new(:not_found, "There's no org globex here.")}

Its agents then can't start or be defined, and no secrets, servers or tokens can be stored for it.

# `settings`

```elixir
@callback settings(org :: String.t(), config :: term()) ::
  {:ok, Wardrik.OrgSettings.t()} | {:error, term()}
```

Returns `org`'s settings, or an error if it doesn't exist.

# `defaults`

```elixir
@spec defaults(Wardrik.t(), String.t()) :: map()
```

Returns the agent `id`'s defaults: the deployment's, overridden by its org's.

# `hold`

```elixir
@spec hold(keyword(), Wardrik.t(), String.t(), Wardrik.OrgSettings.t()) :: keyword()
```

Returns `opts` with the org's policy and ceilings added.

# `known`

```elixir
@spec known(Wardrik.t(), String.t()) :: :ok | {:error, Wardrik.Error.t()}
```

Returns `:ok` if `org` exists, or the error `c:settings/2` returns.

`"deployment"`, the deployment's own namespace, always exists.

# `org`

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

Returns the org of the agent `id`.

# `refresh`

```elixir
@spec refresh(Wardrik.t(), String.t()) :: [String.t()]
```

Applies the org's current settings to its awake agents. Returns a line for each failure.

# `settings`

```elixir
@spec settings(Wardrik.t(), String.t()) ::
  {:ok, Wardrik.OrgSettings.t()} | {:error, Wardrik.Error.t()}
```

Returns `org`'s settings, with each policy and ceiling built, or an error if they're invalid.

Without `:orgs`, every org gets empty settings.

# `spent`

```elixir
@spec spent(atom() | Wardrik.t(), String.t()) ::
  {:ok, %{required(String.t()) => map()}} | {:error, Wardrik.Error.t()}
```

Returns what the org's agents have spent against each ceiling, by name. See
`Wardrik.Ceiling.spent/3`.

    Wardrik.Orgs.spent(MyApp.AgentRuntime, "acme")
    #=> {:ok, %{"spending-cap" => %{limit: %{usd: 20.0, tokens: nil}, spent: %{usd: 12.4, tokens: 81_200}, ...}}}

# `within`

```elixir
@spec within(Wardrik.t(), Wardrik.OrgSettings.t()) :: Wardrik.t()
```

Returns `wardrik` with the org's policies and defaults merged in.

---

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