@xcall/server

SDK Node.js para integração backend com a API do xCall-Accounts.

Zero dependências. TypeScript puro. CJS + ESM. Node 18+.

Instalação

yarn add @xcall/server

Setup

import { XCallServer } from '@xcall/server'

const xcall = new XCallServer({
  apiKey: process.env.XCALL_API_KEY,
  apiSecret: process.env.XCALL_API_SECRET,
  // baseUrl: 'https://accounts.xcall.com.br' (default)
})

| Opção | Tipo | Obrigatório | Descrição | | ----------- | -------- | ----------- | ------------------------------------------ | | apiKey | string | sim | Chave pública da conta B2B | | apiSecret | string | sim | Chave secreta da conta B2B | | baseUrl | string | não | URL do xCall-Accounts (tem default) |

Métodos

createRoomToken(params) — Gerar token JWT de sala

Retorna um JWT que autoriza um participante a entrar numa sala via @xcall/web.

const { token } = await xcall.createRoomToken({
  roomId: 'reuniao-semanal',
  user: {
    externalId: 'user-123',
    displayName: 'João Silva',
  },
  embedOrigin: 'https://meuapp.com.br',
  shareUrl: 'https://meuapp.com.br/sala/reuniao-semanal',
  branding: {
    name: 'Minha Empresa',
    logo: 'https://meuapp.com.br/logo.png',
    primaryColor: '#6366f1',
  },
  features: {
    chat: '1',
    screen_share: '1',
    recording: '0',
  },
  singleUse: false,
  ttlSeconds: 3600,
})

Parâmetros (CreateRoomTokenParams):

| Campo | Tipo | Obrigatório | Descrição | | ------------- | -------------------------- | ----------- | ------------------------------------------------- | | roomId | string | sim | Identificador da sala | | user | XCallUser | não | Dados do participante | | embedOrigin | string | não | Origin autorizado a embedar o iframe | | shareUrl | string | não | URL de convite exibida na sala | | branding | XCallBranding | não | Branding white-label (nome, logo, cor) | | features | Record<string, string> | não | Feature flags ('1' = ativo, '0' = desativado) | | singleUse | boolean | não | Token de uso único | | ttlSeconds | number | não | Tempo de vida do token em segundos |

Resposta: { token: string }

getRoomInfo(roomId) — Info de sala ativa

Consulta se uma sala está ativa, quantos participantes tem e quando começou. Autenticado por api_key + api_secret (não requer JWT de sessão).

const info = await xcall.getRoomInfo('reuniao-semanal')

// info = {
//   active: true,
//   participants_count: 3,
//   started_at: '2026-03-11T14:30:00.000Z'
// }

Resposta (RoomInfoData):

| Campo | Tipo | Descrição | | -------------------- | ---------------- | -------------------------------------- | | active | boolean | Se a sala está ativa agora | | participants_count | number | Quantidade de participantes na sala | | started_at | string \| null | ISO timestamp de início (null se inativa) |

getAccount() — Dados da conta

Retorna dados da conta autenticada. Requer JWT de sessão via withToken().

xcall.withToken(sessionJwt)
const account = await xcall.getAccount()

Resposta (AccountData):

| Campo | Tipo | Descrição | | ------------ | --------- | ---------------------- | | id | string | ID da conta | | name | string | Nome da empresa | | email | string | Email da conta | | api_key | string | Chave pública | | active | boolean | Se a conta está ativa | | created_at | string | Data de criação (ISO) |

getSubscription() — Assinatura ativa

Retorna dados da assinatura/plano. Requer JWT de sessão via withToken().

xcall.withToken(sessionJwt)
const sub = await xcall.getSubscription()

Resposta (SubscriptionData):

| Campo | Tipo | Descrição | | ----------- | -------- | ---------------------------- | | id | string | ID da assinatura | | plan_id | string | ID do plano | | status | string | Status (active, canceled...) | | starts_at | string | Início (ISO) | | ends_at | string | Fim (ISO) |

verifyWebhook(rawBody, signature, secret) — Verificar webhook do SFU

Valida a assinatura de webhooks enviados pelo xCall-SFU (room.started, peer.joined, peer.left, room.ended, room.heartbeat).

app.post('/webhook/xcall', (req, res) => {
  try {
    xcall.verifyWebhook(
      JSON.stringify(req.body),
      req.headers['x-xcall-signature'] as string,
      process.env.XCALL_WEBHOOK_SECRET,
    )
    // webhook válido — processar evento
  } catch (err) {
    // XCallWebhookError — assinatura inválida
    return res.status(401).send({ error: 'Webhook inválido' })
  }
})

Lança XCallWebhookError se a assinatura não bater.

withToken(token) — Injetar JWT de sessão

Injeta um JWT de sessão manualmente. Necessário para getAccount() e getSubscription(). O token é cacheado internamente.

xcall.withToken(sessionJwt)

Retorna this (chainable).

destroy() — Limpar estado

Limpa o cache interno e o token de sessão.

xcall.destroy()

Tipos exportados

import type {
  XCallServerOptions,
  CreateRoomTokenParams,
  XCallUser,
  XCallBranding,
  TokenResponse,
  AccountData,
  SubscriptionData,
  RoomInfoData,
} from '@xcall/server'

Erros

| Classe | Quando | | ------------------- | ------------------------------------------ | | XCallApiError | Resposta HTTP com erro (status + message) | | XCallWebhookError | Assinatura de webhook inválida |

import { XCallApiError, XCallWebhookError } from '@xcall/server'

try {
  await xcall.createRoomToken({ roomId: 'sala' })
} catch (err) {
  if (err instanceof XCallApiError) {
    console.error(err.status, err.message)
  }
}

Regras importantes

• NUNCA fazer fetch manual para /token — sempre usar createRoomToken()
• NUNCA comparar webhook secret manualmente — sempre usar verifyWebhook()
• NÃO usar em Edge Runtime — apenas Node.js 18+
• Sempre usar @xcall/web no frontend — este SDK é exclusivo para backend