npm package: @kazejs/avbr
Description: SDK - TypeScript clientAPI
Latest version: 1.0.6

# Avenia - SDK

Biblioteca Deno TypeScript para integracao com a API da Avenia (plataforma
banking/fintech).

## Install

```shell
deno add jsr:@kazejs/avbr
```

Depois importe no seu codigo:

```typescript
import { AveniaClient } from "@kazejs/avbr";
```

## Uso

### Autenticacao via Bearer Token (JWT)

```typescript
const avenia = new AveniaClient({ bearerToken: "seu-jwt-token" });
```

### Autenticacao via API Key (RSA)

```typescript
// Chave privada sem senha
const avenia = new AveniaClient({
  apiKeyAuth: {
    apiKey: "uuid-da-api-key",
    privateKey: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
  },
});

// Chave privada criptografada (com passphrase)
const avenia = new AveniaClient({
  apiKeyAuth: {
    apiKey: "uuid-da-api-key",
    privateKey:
      "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...\n-----END ENCRYPTED PRIVATE KEY-----",
    passphrase: Deno.env.get("AVENIA_KEY_PASSPHRASE"),
  },
});
```

### Exemplo

```typescript
// Login via OTP
const avenia = new AveniaClient({ environment: "sandbox" });
await avenia.auth.login({ email: "user@example.com" });
const { accessToken } = await avenia.auth.validateLogin({
  email: "user@example.com",
  code: "123456",
});
avenia.setBearerToken(accessToken);

// Consultar conta
const info = await avenia.account.getInfo();
const balances = await avenia.account.getBalances();
```

## Resources disponiveis

| Resource             | Propriedade                  | Descricao                                    |
| -------------------- | ---------------------------- | -------------------------------------------- |
| Account              | `client.account`             | Conta, sub-contas, saldos, limites           |
| API Keys             | `client.apiKeys`             | CRUD de API keys                             |
| Auth                 | `client.auth`                | Login OTP, validacao, refresh token          |
| MFA                  | `client.mfa`                 | TOTP (criacao, validacao, remocao)           |
| Webhooks             | `client.webhooks`            | CRUD de webhooks, eventos, tentativas        |
| Webhook Verification | `client.webhookVerification` | Verificacao de assinatura de webhooks        |
| KYC                  | `client.kyc`                 | Importacao de token KYC                      |
| Quotes               | `client.quotes`              | Cotacoes                                     |
| Tickets              | `client.tickets`             | Tickets (ARS, BRL PIX, USD, EUR, blockchain) |

## CLI

O SDK inclui uma CLI interativa para gerenciar autenticacao, conta e webhooks.

### 1. Execucao direta (sem instalar)

```shell
dx jsr:@kazejs/avbr/cli <comando> <subcomando>
```

### 2. Instalacao global

```shell
deno install -g -A --name avenia jsr:@kazejs/avbr/cli
avenia <comando> <subcomando>
```

### 3. Versoes anteriores do Deno (sem `dx`)

```shell
deno run -A jsr:@kazejs/avbr/cli <comando> <subcomando>
```

### 4. Uso local (desenvolvimento)

```shell
deno task cli <comando> <subcomando>
```

### Comandos disponiveis

| Comando                     | Descricao                              |
| --------------------------- | -------------------------------------- |
| `login otp`                 | Login via OTP (email)                  |
| `login apikey`              | Login via API key (RSA)                |
| `account info`              | Consulta informacoes da conta          |
| `apikeys list`              | Lista API keys registradas             |
| `apikeys register`          | Registra uma nova API key              |
| `quote`                     | Cotacao interativa e criacao de ticket |
| `webhooks manage`           | Gerencia webhooks (menu interativo)    |
| `webhooks manage list`      | Listar webhooks registrados            |
| `webhooks manage create`    | Criar um novo webhook                  |
| `webhooks manage delete`    | Deletar um webhook                     |
| `webhooks`                  | Consulta logs de webhooks (menu)       |
| `webhooks list`             | Listar eventos de webhook              |
| `webhooks watch`            | Watch mode (eventos em tempo real)     |
| `webhooks detail {ID}`      | Ver detalhe de um evento               |
| `webhooks attempts`         | Listar tentativas de entrega (menu)    |
| `webhooks attempts list`    | Listar tentativas de entrega           |
| `webhooks attempts pending` | Tentativas com falha/pendentes         |
| `webhooks attempts ack`     | Confirmar (acknowledge) tentativas     |

### Storage customizado

Por padrao a CLI salva sessao e dados em `./storage/`. Para alterar, use a
variavel de ambiente `AVENIA_STORAGE_PATH`:

```shell
AVENIA_STORAGE_PATH=~/.avenia deno task cli login otp
```

### Scripts individuais (deno tasks)

Os scripts tambem continuam disponiveis como tasks individuais:

```shell
deno task register-apikey   # Registra uma API key
deno task login-otp         # Login via OTP (email)
deno task login-apikey      # Login via API key (RSA)
deno task account-info      # Consulta informacoes da conta
deno task list-apikeys      # Lista API keys registradas
deno task manage-webhooks   # Gerencia webhooks
deno task webhook-logs      # Consulta logs de webhooks
```

## Criação de chaves RSA

REF: https://integration-guide.avenia.io/docs/Security/apiKeysManagements

### Chave sem senha

```shell
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private_key.pem -pubout -out public_key.pem
```

### Chave com senha (recomendado para producao)

```shell
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -aes-256-cbc -pass pass:MINHA_SENHA -out private_key.pem
openssl pkey -in private_key.pem -passin pass:MINHA_SENHA -pubout -out public_key.pem
```

A chave gerada tera o header `BEGIN ENCRYPTED PRIVATE KEY`. Para usar no SDK,
passe o campo `passphrase` no `apiKeyAuth`.

### Variável de ambiente `AVENIA_KEY_PASSPHRASE`

Os scripts utilitarios (`deno task login-apikey`, etc.) leem a passphrase na
seguinte ordem de prioridade:

1. **Variável de ambiente `AVENIA_KEY_PASSPHRASE`** (ideal para CI/CD e
   producao)
2. **Prompt interativo** (pressione Enter para pular se a chave nao tem senha)
3. **Sessao salva** em `storage/avenia-session.json` (gravada no login)

```shell
# Exemplo: login com chave criptografada via env
deno task login-apikey

# Ou exportando antes
export AVENIA_KEY_PASSPHRASE=minha-senha
deno task login-apikey
```

Se a chave privada for criptografada e a variável não estiver definida, o SDK
lançará erro informando que a passphrase é necessária.

A permissão de leitura da env `AVENIA_KEY_PASSPHRASE` ja esta configurada no
`deno.json` (secao `permissions.avenia.env`).

### Formatar chave publica para registro

```shell
sed -e '/^$/d' -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g' public_key.pem
```

## OpenTelemetry

O SDK e instrumentado com [OpenTelemetry](https://opentelemetry.io/). Todas as
chamadas HTTP geram spans automaticamente com `SpanKind.CLIENT` e
`peer.service: "avenia-api"`, fazendo a Avenia aparecer como servico externo no
service map (Jaeger, Grafana Tempo, Datadog, etc).

Se o app consumidor nao configurar OpenTelemetry, os spans sao no-ops (zero
overhead).

### Exemplo com Deno + OpenTelemetry

```typescript
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { AveniaClient } from "@kazejs/avbr";

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: "http://localhost:4318/v1/traces",
  }),
  serviceName: "meu-app",
});
sdk.start();

const avenia = new AveniaClient({ bearerToken: "..." });
await avenia.auth.login({ email: "user@example.com" });
// ^ gera span "avenia POST /v1/auth/login" com atributos HTTP
```

### Atributos do span

| Atributo                    | Exemplo          |
| --------------------------- | ---------------- |
| `http.request.method`       | `POST`           |
| `http.route`                | `/v1/auth/login` |
| `http.response.status_code` | `200`            |
| `avenia.environment`        | `sandbox`        |
| `avenia.sub_account_id`     | `default`        |
| `peer.service`              | `avenia-api`     |

## Links

- [@kazejs/avbr](https://jsr.io/@kazejs/avbr)
- [Guia de integração Avenia](https://integration-guide.avenia.io)
- [Documento adicional Avenia, para token shared SumsSub](https://gist.github.com/rcorrea-brla/a979ad0aef35c7fcfbf547d1f73d780e)