# `Weavr`
[🔗](https://github.com/iamkanishka/weavr/blob/main/lib/weavr.ex#L1)

An Elixir client for the [Weavr](https://weavr.io) Multi embedded banking API.

## Quick start (stateless)

    config = Weavr.Config.new(api_key: System.fetch_env!("WEAVR_API_KEY"), environment: :sandbox)

    {:ok, %{auth_token: token}} =
      Weavr.Auth.login_with_password(config, email: "user@example.com", password: "secret")

    {:ok, accounts} = Weavr.Accounts.list(config, auth_token: token)

## Quick start (stateful `Weavr.Client`)

    {:ok, client} = Weavr.Client.start_link(api_key: "...", environment: :sandbox)
    :ok = Weavr.Client.login_with_password(client, email: "user@example.com", password: "secret")
    {:ok, token} = Weavr.Client.current_token(client)
    {:ok, accounts} = Weavr.Accounts.list(Weavr.Client.config(client), auth_token: token)

## Module overview

### Core

  * `Weavr.Config` — environment-aware configuration (Sandbox/Live, Multi/BackOffice)
  * `Weavr.Client` — stateful GenServer for managing per-user auth sessions
  * `Weavr.Auth` — login, token exchange, identity listing, logout, SCA detection
  * `Weavr.Error` — error struct hierarchy (API, Network, Timeout, InvalidRequest, Decode)

### Resources

  * `Weavr.Corporates` — Corporate identities and KYB
  * `Weavr.Consumers` — Consumer identities and KYC
  * `Weavr.Users` — Authorised Users (and root user listing)
  * `Weavr.Passwords` — password creation, update, and lost-password flow
  * `Weavr.Accounts` — Managed Accounts (IBAN, block/unblock, statement)
  * `Weavr.Cards` — Managed Cards (virtual/physical, spend rules, statement)
  * `Weavr.Transfers` — intra-identity fund transfers
  * `Weavr.Sends` — Outgoing Wire Transfers between identities
  * `Weavr.LinkedAccounts` — external bank account connections
  * `Weavr.StepUp` — SCA/PSD2 step-up challenge initiation and verification
  * `Weavr.AuthenticationFactors` — OTP device/channel enrolment
  * `Weavr.Bulk` — bulk operation lifecycle (submit/execute/pause/resume/cancel)
  * `Weavr.BackOffice` — back-office operations (Bearer token auth)
  * `Weavr.Simulator` — Sandbox-only event simulation (deposits, card purchases, KYC/KYB)

## Error handling

Every function returns `{:ok, result}` or `{:error, Weavr.Error.t()}`.
Use `unwrap!/1` to raise on error when you prefer exceptions:

    account = Weavr.Accounts.get(config, id, auth_token: token) |> Weavr.unwrap!()

## Zero runtime dependencies

`weavr` ships with zero required runtime deps — no Jason, no Hackney, no
Mint. It uses Erlang's built-in `:httpc` and a small vendored JSON codec.
If your app already has `Jason` and/or `:telemetry`, `weavr` detects and
uses them automatically. See `Weavr.JSON` and `Weavr.Telemetry`.

# `unwrap!`

```elixir
@spec unwrap!({:ok, value} | {:error, Weavr.Error.t()}) :: value when value: var
```

Unwraps `{:ok, value}` returning `value`, or raises the error struct on
`{:error, reason}`.

## Examples

    iex> Weavr.unwrap!({:ok, %{"id" => "123"}})
    %{"id" => "123"}

    iex> Weavr.unwrap!({:error, %Weavr.Error.API{status: 404, message: "not found"}})
    ** (Weavr.Error.API) Weavr API error (status 404): not found

---

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