@cactus-agents/sports

SDK multi-provider para integracoes de sportsbook. Suporta tres providers: First (iframe), Altenar (JS SDK) e Betby (JS SDK). Oferece service HTTP, helpers de deep-link, mapeamento de URLs semanticas e utilitarios para carregamento de SDKs externos.

Instalacao

pnpm add @cactus-agents/sports

Uso recomendado

import { createApiClient } from "@cactus-agents/api-client";
import { createSportsFromClient } from "@cactus-agents/sports";

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

// Launch (autenticado)
const { url } = await sports.launch();

// Launch (anonimo)
const { url } = await sports.anonymousLaunch();

// Busca
const results = await sports.search({ term: "futebol" });

// JWT para Betby
const { jwt } = await sports.getBetbyJwt({ user_id: "123" });

API — SportsService

Endpoints

Metodo	Verbo	Endpoint	Descricao
search(params)	GET	/cactus-sportbook/search	Busca esportiva (query params livres)
launch()	GET	/cactus-sportbook/launch	URL iframe First — autenticado
anonymousLaunch()	GET	/cactus-sportbook/anonymous-launch	URL iframe First — anonimo
getBetbyJwt(user)	POST	/betby/get-jwt	Gera JWT para Betby

Providers

First (iframe)

O First funciona via iframe com comunicacao postMessage. O SDK fornece helpers para deep-linking bidirecional:

import {
  buildFirstRedirectUrl,
  buildFirstDeepLink,
  pathEntryFromRoute,
  extractSemanticPath,
  discoveryPathFromLocationChangeEvent,
  sanitizeFirstQueryParams,
} from "@cactus-agents/sports";

Funcao	Descricao
buildFirstRedirectUrl(baseUrl, pathEntry)	Constroi URL com fragmento/query para o iframe
buildFirstDeepLink(pathEntry)	Converte FirstPathEntry em payload postMessage
pathEntryFromRoute(pathname, query, basePath?)	Extrai path entry de uma rota React Router
extractSemanticPath(eventData, basePath?)	Converte evento LOCATION_CHANGE em URL semantica legivel
discoveryPathFromQueryParams(query)	Extrai path entry de query params
discoveryPathFromLocationChangeEvent(data)	Mapeia evento do iframe para query-like object
sanitizeFirstQueryParams(params)	Remove parametros sports-specific das query params
parseSemanticSegment(segment)	Parseia segmento de URL semantica (ex: e-123, l-456)

URLs semanticas

O SDK converte URLs internas do First em URLs legiveis:

/sports/futebol/brasil/flamengo-x-palmeiras/e-816042737861410816
/sports/live     → { eventlistTab: "Live" }
/sports/upcoming → { eventlistTab: "Upcoming" }

Prefixos suportados: e- (evento), l- (liga), s- (esporte), ml- (master league), c- (campeonato).

Altenar (JS SDK)

Helpers para mapeamento bidirecional entre URLs semanticas da app e payloads do SDK Altenar:

import {
  buildAltenarSemanticPath,
  parseAltenarPageFromPath,
} from "@cactus-agents/sports";

Funcao	Descricao
buildAltenarSemanticPath(to, basePath?)	Converte callback onRouteChangeDetailed em URL semantica
parseAltenarPageFromPath(pathname, basePath?, testBasePath?)	Parseia URL back para AltenarSetPayload

Paginas suportadas: overview, live, sport, category, championship, event, liveEvent, results, betHistory, esports, toto, entre outras.

Betby (JS SDK)

Para Betby, o SDK fornece apenas o endpoint JWT. A configuracao e feita via BetbyConfig:

interface BetbyConfig {
  brandId?: string;
  theme?: string;
  libraryUrl?: string;
}

Navegacao

Helpers para resolver paths de menu e detectar o provider ativo:

import { resolveMenuItemPath, getActiveProvider } from "@cactus-agents/sports";

// Resolve path do menu baseado no provider ativo
const path = resolveMenuItemPath(sidebarItem, "altenar");
// → sidebarItem.altenarPath

// Detecta provider ativo pela URL (com basePath customizavel)
const provider = getActiveProvider("/sports/live", config);
// → config.main (ex: "first")

const provider2 = getActiveProvider("/deportes/live", config, {
  sportsBasePath: "/deportes",
  testBasePath: "/deportes-test",
});
// → config.main (brand override)

const testProvider = getActiveProvider("/sports-test/live", config);
// → config.test (ex: "altenar")

Parametro basePath

As funcoes extractSemanticPath(), pathEntryFromRoute(), buildAltenarSemanticPath(), parseAltenarPageFromPath() e getActiveProvider() aceitam um parametro opcional basePath (default: "/sports"). Isso permite que brands com paths customizados (ex: /deportes) passem o base path correto para que deep-links e deteccao de provider funcionem.

No template, o valor correto de basePath vem de routePaths.sports (via Route Registry):

import { routePaths } from "~/utils/routes";
import { getActiveProvider, extractSemanticPath } from "@cactus-agents/sports";

const provider = getActiveProvider(pathname, config, {
  sportsBasePath: routePaths.sports,
  testBasePath: routePaths["sports.test"],
});

const semanticPath = extractSemanticPath(eventData, routePaths.sports);

Carregamento de SDK externo

Utilitarios genericos para carregar scripts de terceiros:

import { loadExternalScript, waitForGlobal } from "@cactus-agents/sports";

// Carrega script Altenar
await loadExternalScript("https://sb1client-altenar.biahosted.com/sdk.js", "altenar-sdk");

// Aguarda global ficar disponivel
const sdk = await waitForGlobal<AltenarWSDK>("AltenarWSDK", {
  interval: 200,  // polling a cada 200ms
  timeout: 30000, // timeout em 30s
});

Tipos principais

Provider

type SportsProvider = "first" | "altenar" | "betby";

Configuracao

interface SportsModuleConfig {
  main: SportsProvider | null;   // provider principal (/sports)
  test: SportsProvider | null;   // provider teste (/sports-test)
  first?: FirstProviderConfig;
  altenar?: AltenarProviderConfig;
  betby?: BetbyConfig;
}

First

FirstPathEntry, FirstPathEntryData, FirstUrlData, FirstDeepLink, FirstLaunchResponse

Altenar

AltenarPage, AltenarPathEntry, AltenarInitPayload, AltenarSetPayload, AltenarProviderConfig

Betby

BetbyConfig, BetbyJwtResponse

Navegacao

SportsSidebarItemBase, WaitForGlobalOptions

Service

SportsFetcher, SportsService, SportsSearchParams, SportsSearchResponse

Arquivos relevantes

Arquivo	Conteudo
src/service.ts	createSportsService, createSportsFromClient
src/first.ts	Helpers de deep-link e URL semantica (First)
src/altenar.ts	Helpers de URL semantica (Altenar)
src/navigation.ts	resolveMenuItemPath, getActiveProvider
src/sdk-loader.ts	loadExternalScript, waitForGlobal
src/types.ts	Todas as interfaces e tipos