Pular para o conteúdo principal

@cactus-agents/user

Serviço de gerenciamento de usuário: perfil, segurança, login history, responsible gaming e income report. Framework-agnostic.

Instalação​

pnpm add @cactus-agents/user

Uso básico​

A forma recomendada é usar createUserFromClient, que aceita um ApiClient diretamente:

import { createApiClient } from '@cactus-agents/api-client';
import { createUserFromClient } from '@cactus-agents/user';

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

const history = await user.getLoginHistory(1);

Uso de baixo nível (fetcher manual)​

Se precisar de controle total sobre o adapter HTTP, use createUserService. O fetcher precisa implementar get, post, patch e delete:

import { createUserService } from '@cactus-agents/user';

const userService = createUserService({
  get: (path) => myHttpClient.get(path),
  post: (path, body) => myHttpClient.post(path, body),
  patch: (path, body) => myHttpClient.patch(path, body),
  delete: (path) => myHttpClient.delete(path),
});

API — UserService​

Perfil​

updateProfile(id, data)​

POST /users/update/{id}

interface UpdateUserPayload {
  captcha_token?: string;
  kyc_id?: number;
  password_check?: string;
  state?: string;
  zipcode?: string;
  city?: string;
  address?: string;
  phone?: string;
  ddi?: string;
  affiliation_code?: string;
  email?: string;
  birth_date?: string;
  terms?: boolean;
  language?: string;
  timezone?: string;
  country?: string;
  gender?: number;
  first_name?: string;
  last_name?: string;
  mother_name?: string;
}

getAddress()​

GET /bff/users/address-by-user — retorna UserAddress.

updateEmail(data)​

PATCH /bff/users/self-email

interface UpdateEmailPayload {
  email: string;
  password_check?: string;
  kyc_id?: number;
}

addPhone(data)​

PATCH /bff/users/add-phone

interface AddPhonePayload {
  phone: string;
  ddi: string;
  password_check?: string;
  kyc_id?: number;
}

updateAddress(data)​

PATCH /bff/users/update-address

interface UpdateAddressPayload {
  street: string;
  city: string;
  state: string;
  zipcode: string;
  password_check?: string;
  kyc_id?: number;
}

updateContracts(type)​

PATCH /bff/users/self-contracts — envia { type }.

type ContractType = 'tc' | 'privacy' | 'lgpd' | 'law' | 'migrate' | 'mkt';

updateMarketing(data)​

PATCH /bff/users/self-mkt

interface UpdateMarketingPayload {
  mkt_accepted: boolean;
}

Segurança​

changePassword(id, data)​

POST /users/change-password/{id}

interface ChangePasswordPayload {
  old_password: string;
  password: string;
  password_confirmation: string;
  captcha_token?: string;
  kyc_id?: number;
}

checkPassword(data)​

POST /bff/users/check-password — retorna { success: boolean }.

toggleTwoFactor(data)​

PATCH /bff/users/self-two-factor

interface TwoFactorPayload {
  type: 'email' | 'sms';
  enabled: boolean;
}

getSocialAccounts()​

GET /bff/users/account-social — retorna SocialAccount[].

connectSocial(type)​

POST /bff/users/account-social/connect/{type}

disconnectSocial(id)​

DELETE /bff/users/account-social/{id}

getLoginHistory(page?)​

GET /bff/users/login-history?page={page} — default page 1.

interface LoginHistoryResponse {
  data: LoginHistoryItem[];
  current_page: number;
  last_page: number;
  per_page: number;
  total: number;
}

interface LoginHistoryItem {
  id: number;
  user_id: number;
  ip: string;
  user_agent: string;
  device?: string;
  location?: string;
  created_at: string;
}

Responsible Gaming​

updateLimits(data)​

PATCH /bff/users/update-limits — atualiza limites de depósito, aposta, perda e/ou tempo.

interface UpdateLimitsPayload {
  user_limit_deposit?: number;
  user_limit_deposit_active?: number;
  user_limit_deposit_period?: string;  // 'daily' | 'weekly' | 'monthly'
  user_limit_bet?: number;
  user_limit_bet_active?: number;
  user_limit_bet_period?: string;
  user_limit_loss?: number;
  user_limit_loss_active?: number;
  user_limit_loss_period?: string;
  user_limit_time?: number;
  user_limit_time_active?: number;
  user_limit_time_period?: string;
  kyc_id?: number;
  password_check?: string;
}

setTimeoutLimits(data)​

PATCH /bff/users/timeout-limits — pausa temporária (1 a 45 dias).

interface TimeoutLimitsPayload {
  user_pause: number;   // dias (1-45)
  reason: number;
  kyc_id?: number;
  password_check?: string;
}

setSelfExclusion(data)​

PATCH /bff/users/self-exclusion — autoexclusão por meses ou permanente.

interface SelfExclusionPayload {
  user_exclusion: number;  // meses (3, 6, 12, 24, 36, 60) ou -1 permanente
  reason: number;
  kyc_id?: number;
  password_check?: string;
}

Income Report (IRPF)​

generateIncomeReport(data)​

POST /income-report/generate — retorna IncomeReportData.

interface IncomeReportGeneratePayload {
  reference_year: number;
  type: 'email' | 'download';
}

getIncomeReportStatus(id)​

GET /income-report/{id} — retorna IncomeReportData. Usado para polling até o status mudar.

interface IncomeReportData {
  id: number;
  reference_year: number;
  status: 1 | 2 | 3 | 4;  // 1=pendente, 2=processando, 3=concluído, 4=falhou
  delivery_type: 'email' | 'download';
  requested_at: string;
  generated_at: string | null;
  path: string | null;
  download_url: string | null;
}

getAvailableYears()​

GET /income-report/available-years — retorna { years: number[] }.

Wallet​

Compatibilidade legada

O módulo de wallet foi extraído para @cactus-agents/wallet. No @cactus-agents/user permanecem apenas re-exports e compatibilidade temporária.

Para novos fluxos, use:

  • createWalletFromClient
  • fetchWalletData
  • aggregateWalletData

Documentacao completa em @cactus-agents/wallet.

Transform​

transformWalletResponse(raw)​

transformWalletResponse permanece exportado por compatibilidade, mas o uso recomendado e importar de @cactus-agents/wallet.

Tipos principais​

UserLimits​

Retornado dentro do userInfo pelo getUserProfile do auth. Contém todos os limites e exclusões do usuário:

interface UserLimits {
  user_pause: number;
  user_pause_at: string | null;
  user_pause_in: string | null;
  user_pause_min: string | null;
  user_exclusion: number;
  user_exclusion_at: string | null;
  user_exclusion_in: string | null;
  user_exclusion_min: string | null;
  user_limit_deposit: number;
  user_limit_deposit_active: number;
  user_limit_deposit_period: string;
  user_limit_deposit_change: string | null;
  user_limit_bet: number;
  user_limit_bet_active: number;
  user_limit_bet_period: string;
  user_limit_bet_change: string | null;
  user_limit_loss: number;
  user_limit_loss_active: number;
  user_limit_loss_period: string;
  user_limit_loss_change: string | null;
  user_limit_time: number;
  user_limit_time_active: number;
  user_limit_time_period: string;
  user_limit_time_change: string | null;
  operator_exclusion: number;
  operator_exclusion_at: string | null;
  operator_exclusion_note: string;
  spa_exclusion: number;
  spa_exclusion_at: string | null;
  spa_exclusion_note: string;
}

Wallet​

interface Wallet {
  real: RealWallet;
  bonus: BonusWallet;
  cashback: CashbackWallet;
}

interface RealWallet {
  credit: number;
  walletId: number;
  withdrawEnabled: boolean;
  minWithdrawAmount: number;
  maxWithdrawAmount: number;
  hasWalletDeposit: boolean;
  withdrawEnableNow: boolean;
  withdrawNextDate: string;
}

interface BonusWallet {
  credit: number;
  creditHold: number;
  sportsAmountHold: number;
  casinoAmountHold: number;
  expiryDatetime: string;
}

interface CashbackWallet {
  credit: number;
  expiresAt: string;
}

UserFetcher​

Interface que o createUserService espera receber:

interface UserFetcher {
  get<T>(path: string): Promise<T>;
  post<T>(path: string, body?: unknown): Promise<T>;
  patch<T>(path: string, body?: unknown): Promise<T>;
  delete<T>(path: string): Promise<T>;
}

Diferente do ClientLike (get/post), o UserFetcher exige também patch e delete. O wrapper createUserFromClient faz a conversão automaticamente.