Pular para o conteúdo principal

SDK — @cactus-agents/* Packages

O SDK vive em front-cactus-core/, um monorepo pnpm com pnpm-workspace.yaml.

Os pacotes são publicados no GitHub Packages como registry npm privado da org cactus-agents.

Pacotes publicados​

16 hoje — a lista viva é front-cactus-core/packages/*/package.json (nome + versão saem de lá).

PacoteVersãoDescrição
@cactus-agents/accounts2.9.0Auth + conta do usuário + carteira. Sucessor de auth/user/wallet. Tem subpath /react com a store e os hooks
@cactus-agents/api-client0.18.4HTTP client framework-agnostic (fetch), cache server/client, classificação de erros, refresh-on-401
@cactus-agents/brand0.8.0Transform API → BrandConfig
@cactus-agents/country-config0.15.0Catálogo mundial de países, DDI, moedas, validadores de documento
@cactus-agents/games2.2.1Casino games, páginas curadas, categorias, providers, start-game, votos, stats
@cactus-agents/gamification0.13.0Smartico (logado + visitante) + módulo de rewards via BFF + helpers de display
@cactus-agents/i18n0.103.0Traduções e namespaces (1 idioma por build)
@cactus-agents/kyc0.10.0KYC service + helpers de status; subpaths /unico e /sumsub
@cactus-agents/mocks1.3.0Deprecated. Todos os arquivos de src/ são stubs vazios — os mocks foram substituídos por integrações reais de API. Não é dependência de nenhum consumidor
@cactus-agents/payments0.22.0Providers, depósito, saque, PIX/SPEI, bank-list, contas MX/CHL
@cactus-agents/platform-cache0.14.0Engine de cache multi-camada (memory + CF Cache API + KV)
@cactus-agents/sports0.6.0Sportsbook multi-provider (First, Altenar, Betby, Rogue)
@cactus-agents/sweepstakes0.6.0Dual-currency GC/SC: saldos, troca de moeda, resgate, loja de Gold Coins
@cactus-agents/types0.7.0Tipos canônicos compartilhados (só interfaces, zero lógica)
@cactus-agents/utils1.3.0Helpers compartilhados (imagens/CDN, device, bot, player)
@cactus-agents/validations0.8.0Engine de regras — force/regulatory/global + contexts, predicados

:::caution auth, user e wallet não existem mais Os três foram removidos do monorepo em 2026-04-17 (core 452450e) e unificados em @cactus-agents/accounts (eac3812). pnpm add @cactus-agents/auth falha. Os diretórios packages/{auth,user,wallet}/ que sobraram no repo não têm src/ nem package.json — são cascas de dist/ velho. Tabela de migração símbolo-a-símbolo em accounts. :::

:::note Não todo @cactus-agents/* mora aqui @cactus-agents/sports-rogue (^0.29.2 no front-web-base) é dependência real mas é publicada fora deste monorepo — não tem página nesta seção. @cactus-agents/sports só expõe o RogueProviderConfig; o SDK React do provider Rogue vem desse outro pacote. Logo, esta tabela não é a superfície completa do scope npm. :::

Tooling​

Cada pacote segue a mesma configuração:

  • Build: tsup (ESM + CJS + .d.ts)
  • Testes: Vitest
  • TypeScript: strict mode
  • Lint/format: Biome (versão pinada em front-cactus-core/package.json → devDependencies["@biomejs/biome"])
  • Pre-commit: Husky + lint-staged

Comandos​

cd front-cactus-core

pnpm build     # Build todos os pacotes
pnpm test      # Rodar todos os testes
pnpm lint      # Biome lint

Para rodar os testes de um pacote só:

cd packages/games && npx vitest run

Convenção de interface​

Todos os pacotes que fazem HTTP seguem o padrão de fetcher injection, mantendo-os framework-agnostic. O fetcher mínimo é get + post:

interface BrandFetcher {
  get(path: string): Promise<unknown>;
  post(path: string, body: unknown): Promise<unknown>;
}

Alguns pacotes exigem mais verbos — UserFetcher (accounts) precisa de patch e delete, GamesFetcher precisa de delete.

Wrappers createXFromClient (recomendado)​

Para quem usa o @cactus-agents/api-client, cada pacote expõe um wrapper de conveniência que aceita o ApiClient diretamente — sem montar o fetcher à mão:

import { createApiClient } from "@cactus-agents/api-client";
import {
  createAuthFromClient,
  createRecoveryFromClient,
  createUserFromClient,
  createWalletFromClient,
} from "@cactus-agents/accounts";
import { createBrandFromClient } from "@cactus-agents/brand";
import { createGamesFromClient } from "@cactus-agents/games";
import { createKycFromClient } from "@cactus-agents/kyc";
import { createPaymentsFromClient } from "@cactus-agents/payments";
import { createSportsFromClient } from "@cactus-agents/sports";

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

const auth = createAuthFromClient(client);
const user = createUserFromClient(client);
const wallet = createWalletFromClient(client);
const recovery = createRecoveryFromClient(client);
const brand = await createBrandFromClient(client, { country: "BRA", language: "pt-br" });
const games = createGamesFromClient(client);
const payments = createPaymentsFromClient(client);
const kyc = createKycFromClient(client);
const sports = createSportsFromClient(client);
PacoteWrapperFunção de baixo nível
@cactus-agents/accountscreateAuthFromClient(client)createAuthService(fetcher)
@cactus-agents/accountscreateUserFromClient(client)createUserService(fetcher)
@cactus-agents/accountscreateWalletFromClient(client)createWalletService(fetcher)
@cactus-agents/accountscreateRecoveryFromClient(client)createRecoveryService(fetcher)
@cactus-agents/brandcreateBrandFromClient(client, opts)createBrandConfig(opts)
@cactus-agents/gamescreateGamesFromClient(client)createGamesService(fetcher)
@cactus-agents/gamificationcreateRewardsFromClient(client)createRewardsService(fetcher)
@cactus-agents/kyccreateKycFromClient(client)createKycService(fetcher)
@cactus-agents/paymentscreatePaymentsFromClient(client)createPaymentsService(fetcher)
@cactus-agents/sportscreateSportsFromClient(client)createSportsService(fetcher)
@cactus-agents/sweepstakescreateSweepstakesFromClient(client)createSweepstakesService(fetcher)
@cactus-agents/validations— (import direto)fetchAllValidations(input)

Fetcher manual (baixo nível)​

Para uso com HTTP clients arbitrários (não-ApiClient), injete um fetcher manualmente:

const brand = await createBrandConfig({
  fetcher: { get: myClient.get, post: myClient.post },
  country: "BRA",
  language: "pt-br",
});