@cactus-agents/wallet

SDK framework-agnostic para carteira, bonus, cashback, rollover e transacoes.

Instalacao

pnpm add @cactus-agents/wallet

Uso recomendado

Use createWalletFromClient quando voce ja estiver usando @cactus-agents/api-client:

import { createApiClient } from "@cactus-agents/api-client";
import { createWalletFromClient, fetchWalletData } from "@cactus-agents/wallet";

const client = createApiClient({ baseUrl, tenant, language });
const wallet = createWalletFromClient(client);

const data = await fetchWalletData(wallet);
// data.wallet.real.credit
// data.rollover.accomplished

API publica

Exports principais:

• createWalletService(fetcher)
• createWalletFromClient(client)
• fetchWalletData(service)
• transformWalletResponse(raw)
• transformTransaction(raw)
• transformTransactionResponse(raw)
• transformRollover(raw, accomplished)
• aggregateWalletData(walletRaw, rolloverRaw, accomplishedRaw)

Tipos principais:

• Wallet, RealWallet, BonusWallet, CashbackWallet
• Rollover, RolloverRaw, RolloverAccomplished
• Transaction, TransactionResponse, TransactionFilter
• WalletData, WalletService, WalletFetcher

Referencia de exports: front-cactus-core/packages/wallet/src/index.ts.

Endpoints do WalletService

Metodo	Endpoint	Observacao
getWallet()	GET /users/wallet	Dados raw da carteira
getTransactions(filter)	POST /bff/transactions	Historico com filtros
getCashbackTransactions(page, datePeriod)	GET /transactions/cashback	Cashback por periodo
getRollover()	GET /bonus/rollover	Dados de rollover
checkRolloverAccomplished()	GET /bonus/rollover-accomplished	Status de rollover
transferBonus()	POST /bonus/transfer	Transferencia de bonus
transferCashback()	POST /cashback/transfer	Resgate de cashback
getWithdrawReceipt(id)	GET /withdraw/{id}/generate	Comprovante de saque

Agregacao e normalizacao

O pacote oferece agregacao em um unico objeto com aggregateWalletData:

import { aggregateWalletData } from "@cactus-agents/wallet";

const walletData = aggregateWalletData(walletRaw, rolloverRaw, accomplishedRaw);

Formato final:

interface WalletData {
  wallet: Wallet;
  rollover: Rollover; // inclui rollover.accomplished
}

Regra de otimizacao de rollover

Use fetchWalletData(service) para evitar chamadas desnecessarias que podem retornar erro de carteira de bonus vazia:

1. Busca getWallet() primeiro
2. Verifica se bonus tem saldo (bonus_wallet_result.credit > 0)
3. Verifica expiracao (expiry_datetime no futuro)
4. So chama getRollover() e checkRolloverAccomplished() quando bonus esta ativo
5. Se bonus vazio/expirado, retorna defaults via aggregateWalletData

Isso reduz erro 400 e evita requests desnecessarios.

Referencia: front-cactus-core/packages/wallet/src/service.ts.

Integracao server-side (recomendado para JWT HttpOnly)

Quando o token fica em cookie HttpOnly, a chamada deve passar por loader/action no servidor:

import { createWalletFromClient, fetchWalletData } from "@cactus-agents/wallet";

export async function action({ request, context }: Route.ActionArgs) {
  const client = createClient(context.cloudflare.env, { request });
  const walletService = createWalletFromClient(client);
  const walletData = await fetchWalletData(walletService);
  return { ok: true, data: walletData };
}

No front-web-base, esse padrao ja e usado nas rotas api.wallet.*.

Notas de transform

• transformWalletResponse converte valores de carteira de centavos para unidade monetaria (/ 100).
• transformTransactionResponse converte paginacao para camelCase.
• transformRollover normaliza first_transaction para firstTransaction e aplica accomplished.