Avenia - SDK

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

Install

deno add jsr:@kazejs/avbr

Depois importe no seu codigo:

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

Uso

Autenticacao via Bearer Token (JWT)

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

Autenticacao via API Key (RSA)

// 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

// Login via OTP
const avenia = new AveniaClient({ environment: "sandbox" });
await avenia.auth.login({ email: "[email protected]" });
const { accessToken } = await avenia.auth.validateLogin({
  email: "[email protected]",
  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)

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

2. Instalacao global

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

3. Versoes anteriores do Deno (sem dx)

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

4. Uso local (desenvolvimento)

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:

AVENIA_STORAGE_PATH=~/.avenia deno task cli login otp

Scripts individuais (deno tasks)

Os scripts tambem continuam disponiveis como tasks individuais:

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

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)

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)

# 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

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

OpenTelemetry

O SDK e instrumentado com OpenTelemetry. 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

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: "[email protected]" });
// ^ 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
• Guia de integração Avenia
• Documento adicional Avenia, para token shared SumsSub