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 implementados

Pacote	Descrição	Testes
@cactus-agents/api-client	HTTP client framework-agnostic (fetch)	22
@cactus-agents/types	Tipos canônicos compartilhados	—
@cactus-agents/brand	Transform API → BrandConfig	26
@cactus-agents/auth	Auth service + token refresh	18
@cactus-agents/utils	Helpers compartilhados (images, CDN)	15
@cactus-agents/user	Perfil, segurança, responsible gaming e income report	30
@cactus-agents/wallet	Carteira, bonus, cashback, rollover e transacoes	29
@cactus-agents/payments	Providers, depósito, saque, PIX/SPEI/MX, bank-list	—
@cactus-agents/games	Casino games, categorias, providers, start-game, votes, stats, image helpers	—
@cactus-agents/gamification	Smartico SDK — service logado + visitante, hash, widget actions, events	—
@cactus-agents/sports	Sportsbook multi-provider (First, Altenar, Betby)	—
@cactus-agents/kyc	KYC service (start, status), helpers de status, multi-operador	—
@cactus-agents/validations	Engine de regras — force/regulatory/global+contexts, 10 módulos, predicados	—

Pacotes planejados

Pacote	Descrição
@cactus-agents/pusher	WebSocket real-time

Tooling

Cada pacote segue a mesma configuração:

• Build: tsup (ESM + CJS + .d.ts)
• Testes: Vitest
• TypeScript: strict mode
• Lint/format: Biome 1.9.4
• 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

Convenção de interface

Todos os pacotes que fazem HTTP seguem o padrão de fetcher injection, mantendo-os framework-agnostic:

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

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 necessidade de montar o fetcher manualmente:

import { createApiClient } from '@cactus-agents/api-client';
import { createAuthFromClient } from '@cactus-agents/auth';
import { createBrandFromClient } from '@cactus-agents/brand';
import { createUserFromClient } from '@cactus-agents/user';
import { createWalletFromClient } from '@cactus-agents/wallet';
import { createPaymentsFromClient } from '@cactus-agents/payments';
import { createGamesFromClient } from '@cactus-agents/games';

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

const auth = createAuthFromClient(client);
const brand = await createBrandFromClient(client, { country: 'BRA', language: 'pt-br' });
const user = createUserFromClient(client);
const wallet = createWalletFromClient(client);
const payments = createPaymentsFromClient(client);
const games = createGamesFromClient(client);
const kyc = createKycFromClient(client);

Pacote	Wrapper	Função de baixo nível
@cactus-agents/auth	createAuthFromClient(client)	createAuthService(fetcher)
@cactus-agents/brand	createBrandFromClient(client, opts)	createBrandConfig(opts)
@cactus-agents/user	createUserFromClient(client)	createUserService(fetcher)
@cactus-agents/wallet	createWalletFromClient(client)	createWalletService(fetcher)
@cactus-agents/payments	createPaymentsFromClient(client)	createPaymentsService(fetcher)
@cactus-agents/games	createGamesFromClient(client)	createGamesService(fetcher)
@cactus-agents/kyc	createKycFromClient(client)	createKycService(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',
});