@cactus-agents/types

Source of truth para tipos compartilhados entre pacotes. Não contém lógica — apenas interfaces e tipos TypeScript. O barrel é export type * de três módulos: brand.ts, common.ts e feature-flags.ts.

Instalação

pnpm add @cactus-agents/types

BrandConfig

O tipo principal que representa toda a configuração de uma marca:

interface BrandConfig {
  appearance: BrandAppearance;
  features: BrandFeatures;
  settings: BrandSettings;
}

:::caution O BrandConfig foi podado — o raw do BFF não Em 2026-07-15 o commit 116c234 ("perf(brand)!: slim do BrandConfig") removeu 26 campos do shape transformado: 2 de appearance, 20 de features e 4 de settings. Motivo: zero consumidores em base e core, mas o BrandConfig viaja no turbo-stream de toda página e em todos os tiers de cache (terms, só ele, eram ~39KB de T&C).

O payload raw do BFF continua enviando esses campos — só o BrandConfig transformado deixou de expô-los. Ou seja: brand.features.gamesDemoMode hoje é undefined em runtime.

Para reativar um campo é preciso descomentar em dois lugares: no bloco // ── Removidos do shape (slim 2026-07-15) de packages/types/src/brand.ts e no transform correspondente (packages/brand/src/transform/{appearance,features,settings}.ts). Só um dos dois não funciona.

Campos removidos, para quem estiver migrando doc/código antigo:

• appearance: cssCode, themeColors
• features: biggestWinnersCarousel, recentWinnersCarousel, topBarFiveItems, gamesDemoMode, gamesShowRtpInfo, homeAsSportsbook, newAuthButtons, newAuthButtonsPill, newAuthFlow, registerChoiceType, registerChoiceTypeTitle, registerChoiceTypeSubtitle, kycIntegrationName, modulesActive, activeModules, modulesWithdraw, activeWithdrawModules, enabledWidgets, contractsSection, migrationDate
• settings: terms, footerExtraCode, texts, spaLimits :::

BrandAppearance

Dados visuais vindos de GET /appearance:

interface BrandAppearance {
  logo: string;
  logoIcon: string;
  /** Banners da home, ordenados por `order`. */
  banners: Banner[];
  casinoBanners: Banner[];
  popupBanners: Banner[];
  recommendedBanners: { desktop: Banner[]; mobile: Banner[] };
  social: BrandSocial;
  links: BrandLinks;
  footerEmails: BrandFooterEmails;
  sponsorships: BrandSponsorship[];
}

BrandFeatures

Feature flags vindos de GET /bff/features:

interface BrandFeatures {
  socialAuth: { facebook: boolean; google: boolean; steam: boolean; twitch: boolean };
  cookieConsentPopup: boolean;
  casinoNomenclature: string;
  maintenanceMode: boolean;
  authConfig: BrandAuthConfig;
  accountSetLimits: boolean;
  accountTimeoutLimits: boolean;
  kycIntegration: boolean;
  userMigration: boolean;
  migrationNewDomain: string | null;
  contacts: BrandContacts;
  authValidation: BrandValidationModules;
  companyData: unknown[];
  country: BrandCountry;
}

:::note Feature flags de UI não vêm daqui BrandFeatures é o que o BFF manda. As flags de comportamento de UI resolvidas em build-time são AppFeatureFlags (ver abaixo) e as configs em ~/config/features/* do front-web-base. :::

BrandSettings

Configurações de negócio vindas de POST /bookmaker-settings:

interface BrandSettings {
  name: string;
  seoH1: string;
  seoTitle: string;
  seoDescription: string;
  email: string;
  phone: string | null;
  defaultLanguage: string;
  country: string;

  deposit: {
    /** Centavos */
    min: number;
    max: number;
    cashInActive: boolean;
    message: string | null;
  };

  withdrawal: {
    min: number; max: number; maxPerDay: number;
    intervalType: string; timeBetween: number;
    maxAutoAmount: number; dailyMaxAmount: number;
    autoWithdrawActive: boolean; multiplierToAllowFirst: number;
  };

  betting: {
    minBetAmount: number | null;
    maxBetAmount: number | null;
    minQuota: number | null;
    maxQuota: number | null;
    enablePin: boolean;
  };

  bonus: {
    firstDeposit: { active: boolean; percentage: number; max: number; message: string | null };
    referral: { active: boolean; amount: number; type: string; minDepositToGet: number };
  };

  rollover: {
    casinoExpiresIn: number; sportsExpiresIn: number;
    multiplierRealValue: number; casinoMultiplier: number;
    casinoEnabled: boolean; moneyRolloverActive: boolean;
  };

  registration: {
    simplified: boolean; requestDocument: boolean;
    requestBirthdate: boolean; requestPhone: boolean;
  };

  legitimuz: { active: boolean; checkWithdrawActive: boolean; blockWithdrawMinValue: number };

  analytics: {
    gtmId: string | null;
    /** URL de proxy custom do GTM (ex: Stape server-side). `null` = CDN padrão do Google. */
    gtmProxyUrl: string | null;
    /** Kill switch de GTM por brand. */
    disableGtm: boolean;
    pixelId: string | null;
    pixelApi: { id: string; token: string };
    taboolaId: string | null;
    clarityId: string | null;
    kwaiPixelId: string | null;
    /** URL do endpoint de proxy S2S do AppsFlyer. */
    appsFlyerEndpoint: string | null;
  };

  footerHtml: string | null;
  appKeys: Record<string, unknown>;
  zendeskLoginUser: boolean | null;
}

:::note Nullable em betting e bonus.firstDeposit.message Os quatro valores de betting (minBetAmount, maxBetAmount, minQuota, maxQuota) e bonus.firstDeposit.message são | null. Trate a ausência explicitamente em vez de assumir 0 / "". :::

AppFeatureFlags

Flags de front-end resolvidas em build-time via aliases do Vite — não vêm da API:

interface AppFeatureFlags {
  /** DDI select renderizado mas travado no formulário de registro. */
  lockDdiSelection: boolean;
  /** Select de nacionalidade escondido da UI (o código default segue no payload). */
  hideNationalitySelection: boolean;
}

Tipos auxiliares

Definidos em packages/types/src/common.ts.

Tipo	Campos
Banner	image, order, action, actionType, mobileImage, expireAt, alt, altMobile
BrandSocial	tiktok, twitter, youtube, facebook, instagram
BrandSponsorship	id, name, banner, pageUrl, text, icon, order, isMain
BrandContactEntry	phone, link, email
BrandContacts	sac, general, support, complaints, customerService
ValidationModuleEntry	active, modules, frequent, minValue, device
BrandValidationModules	casino, global, sports, deposit, register, withdraw, updateData, firstDeposit, updateLimits, firstWithdraw
AuthSecurity	livenessNewDevice, livenessNewLocation, livenessPasswordChanged, livenessSevenDaysInactive, dialogWeakPassword, changeWeakPasswordRequired
BrandAuthConfig	security, captcha (captchaStyle, enableCaptcha*), registro (register*), twoFactorAuthActive, authFlowVersion, authLayoutVersion + campos opcionais de compat (captchaServices, turnstileSiteKey, recaptchaSiteKey, singleStepFirstOnlyCpf, …)

Definidos em packages/types/src/brand.ts.

Tipo	Campos
BrandCountry	id, name, code, currency, ddi
BrandLinks	blog, appDownload, promotions, promotionsIframe, promotionsWpApi, affiliates, affiliatesLabel, reclameAqui, telegram, telegramLabel, helpCenter, centralizedExclusion — todos string | null
BrandFooterEmails	legal, partner, support — todos string | null

:::note registerValidatePhone Em BrandAuthConfig, quando registerValidatePhone e registerRequestPhone estão ambos true, o fluxo de registro ganha um passo intermediário de OTP por SMS: o base faz POST /bff/register/validate-phone com { email, ddi, phone } e depois envia o código confirmado como validate_code no endpoint normal de registro. :::