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

Sandbox-only simulator endpoints for testing.

**These endpoints only work in the Sandbox environment** — calling them
in Live will return errors. They are used to simulate external events that
Weavr doesn't normally trigger (e.g. incoming bank transfers, card purchases)
so you can test the full lifecycle of your application without real banking
networks.

Confirmed from Weavr's developer documentation:

> "Our Sandbox environment includes a simulator that simulates external events
> not usually triggered by Weavr, for example, receipt of a bank transfer
> or a purchase on a card."

## Confirmed capabilities

  * Simulate incoming wire transfers (IWTs) to a Managed Account
  * Simulate card purchases (authorise/settle/reverse)
  * Simulate identity verification (KYC/KYB) outcomes
  * IWT simulation supports specifying sender information

## Confirmed base path

Simulator endpoints are at `/simulator` under the Multi Sandbox base URL,
e.g. `https://sandbox.weavr.io/multi/simulator/...`.

## Important note on path naming

The simulator endpoint paths are documented in Weavr's Sandbox guide and
a separate Simulator API spec. The paths below are confirmed from
Weavr's published documentation. Always use this module only with a
`:sandbox` environment config.

# `assert_sandbox!`

```elixir
@spec assert_sandbox!(Weavr.Config.t()) :: :ok
```

Guards against accidentally calling Simulator in a non-sandbox environment.

Called automatically by all simulator functions. Raises `Weavr.Error.InvalidRequest`
if `config.environment` is `:live`.

# `simulate_card_purchase`

```elixir
@spec simulate_card_purchase(Weavr.Config.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Simulates a card purchase (authorisation) on a managed card.

`POST /simulator/managed_cards/{id}/authorisation`

`attrs` must include:
- `"transactionAmount"` — `%{"currency" => "GBP", "amount" => 1000}`
- `"merchantCategoryCode"` — MCC code string

# `simulate_card_settlement`

```elixir
@spec simulate_card_settlement(Weavr.Config.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Simulates settling a previously-authorised card transaction.

`POST /simulator/managed_cards/{id}/settlement`

Pass the `transactionId` from the authorisation response in `attrs`.

# `simulate_deposit`

```elixir
@spec simulate_deposit(Weavr.Config.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Simulates an incoming wire transfer (IWT) to a managed account.

`POST /simulator/managed_accounts/{id}/deposits`

`attrs` may include:
- `"transactionAmount"` — object with `"currency"` and `"amount"` (minor units)
- `"senderInformation"` — object with sender details (name, IBAN, etc.)
  for testing IWT screening rules

Requires stepped-up `auth_token`.

# `simulate_kyb`

```elixir
@spec simulate_kyb(Weavr.Config.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Simulates a KYB/KYC outcome for an identity (Approved or Rejected).

Useful for bypassing the KYB/KYC UI flow during Sandbox integration testing.

`POST /simulator/corporates/{id}/kyb` or `/simulator/consumers/{id}/kyc`

`attrs` must include:
- `"corporateId"` or `"consumerId"` — the identity id
- `"kybState"` / `"kycState"` — e.g. `"APPROVED"` or `"REJECTED"`

# `simulate_kyc`

```elixir
@spec simulate_kyc(Weavr.Config.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

---

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