# wallet_api_contracts

**OTP app:** `:wallet_api_contracts`
**Module namespace:** `WalletApiContracts.*`
**Owner:** API Platform Team

## Responsibilities
Versioned API schema contracts and standard JSON error/success envelopes.

Implements the canonical response contract defined in **ADR 0005**.

## Public API

### `WalletApiContracts.ErrorEnvelope`
Build canonical error response maps.
```elixir
WalletApiContracts.ErrorEnvelope.build(
  "INSUFFICIENT_FUNDS",
  "Balance too low for requested debit",
  :business,
  false,
  request_id: "req_abc",
  correlation_id: "corr_xyz"
)
```

### `WalletApiContracts.SuccessEnvelope`
Build canonical success response maps with idempotency replay metadata.
```elixir
WalletApiContracts.SuccessEnvelope.build(
  %{transfer_id: "trf_123", status: "completed"},
  idempotency_key: "idem_abc",
  idempotency_replayed: false
)
```

### `WalletApiContracts.ErrorCodes`
Registry of stable machine-readable error code strings (ADR 0005 governance).
```elixir
WalletApiContracts.ErrorCodes.insufficient_funds()       # => "INSUFFICIENT_FUNDS"
WalletApiContracts.ErrorCodes.idempotency_key_required() # => "IDEMPOTENCY_KEY_REQUIRED"
WalletApiContracts.ErrorCodes.all()                      # => [list of all codes]
```

## Error Code Governance (ADR 0005)
1. New error codes require a registry update in `ErrorCodes` and a changelog entry.
2. Backward-incompatible envelope changes require an API version bump.
3. Public API docs and contract tests must be updated for any semantic change.

## Contract Test Requirements (ADR 0005)
- Contract tests for all standard error codes and envelope fields.
- Replay tests for duplicate write requests with same idempotency key.
- Conflict tests for same key with different payload.
- Header propagation tests for request/correlation/idempotency IDs.

## Allowed Dependencies
- `wallet_shared_kernel` - Correlation ID and timestamp helpers
- `jason` - JSON encoding (for payload hashing)