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)	14
@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

Pacotes planejados

Pacote	Descrição
@cactus-agents/user	CRUD de usuário, update profile, wallet
@cactus-agents/payments	Depósito/saque, payment providers por país
@cactus-agents/kyc	Validação de documentos, liveness
@cactus-agents/responsible-gaming	Timeout limits, self-exclusion
@cactus-agents/games	Casino games filter, stats, top/last wins
@cactus-agents/sports	Integração First (sportbook)
@cactus-agents/gamification	Smartico — rewards, redeem
@cactus-agents/income-report	Geração + polling de relatório IRPF
@cactus-agents/feature-flags	ConfigCat + JSON + env var
@cactus-agents/pusher	WebSocket real-time
@cactus-agents/validations	Validators por país

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';

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

const auth = createAuthFromClient(client);
const brand = await createBrandFromClient(client, { country: 'BRA', language: 'pt-br' });

Pacote	Wrapper	Função de baixo nível
@cactus-agents/auth	createAuthFromClient(client)	createAuthService(fetcher)
@cactus-agents/brand	createBrandFromClient(client, opts)	createBrandConfig(opts)

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',
});