SDK TypeScript

O pacote @mencionai/sdk é a forma mais simples de chamar a API MencionAI a partir de Node.js, funções serverless ou qualquer backend TypeScript/JavaScript.

Instalação

pnpm add @mencionai/sdk

npm install @mencionai/sdk

Início rápido

import { MencionAiClient } from '@mencionai/sdk';

const client = new MencionAiClient({
  apiKey: process.env.MENCIONAI_API_KEY!,
});

const org = await client.getOrganization();
console.log(org.name, org.plan);

const { workspaces } = await client.listWorkspaces();

if (workspaces[0]) {
  const summary = await client.getVisibilitySummary(workspaces[0].id);
  console.log(summary.brand_name, summary.total_mentions, 'menções');
}

A URL base padrão é https://www.mencionai.com/api/v1. Sobrescreva se necessário:

const client = new MencionAiClient({
  apiKey: process.env.MENCIONAI_API_KEY!,
  baseUrl: 'https://www.mencionai.com/api/v1',
});

Obter sua chave de API

Entre em MencionAI.
Vá em Configurações → Chaves de API.
Crie uma chave e armazene em MENCIONAI_API_KEY (ou seu gerenciador de segredos).

Nunca use chaves de API em código do navegador — chame a API sempre no servidor.

Métodos

Organização e workspaces

await client.getOrganization();
await client.listWorkspaces();
await client.getWorkspace(42);

Visibilidade

const summary = await client.getVisibilitySummary(42);
// summary.prompts_tracked, summary.total_mentions, summary.total_citations, …

Scans

Enfileire um scan com uma chave de idempotência única (ex.: UUID ou seu próprio id de deduplicação):

const { job_id, status } = await client.enqueueScan(42, 'scan-run-2026-07-06-001');

let job = await client.getJob(job_id);
while (job.status === 'pending' || job.status === 'processing') {
  await new Promise((r) => setTimeout(r, 3000));
  job = await client.getJob(job_id);
}

console.log('Scan finalizado:', job.status);

Webhooks

const { endpoints } = await client.listWebhooks();

const endpoint = await client.createWebhook({
  url: 'https://seu-app.com/webhooks/mencionai',
  events: ['visibility.scan.completed'],
});

// Salve endpoint.secret — exibido apenas na criação
console.log('Webhook secret:', endpoint.secret);

Tokens de embed

const { token, expires_in } = await client.createEmbedToken({
  workspace_id: 42,
  ttl_sec: 3600,
});

const iframeUrl = `https://www.mencionai.com/embed/v1/workspaces/42/summary?token=${token}`;

Tratamento de erros

Requisições com falha lançam MencionAiError:

import { MencionAiClient, MencionAiError } from '@mencionai/sdk';

try {
  await client.getOrganization();
} catch (err) {
  if (err instanceof MencionAiError) {
    console.error(err.code);       // ex. RATE_LIMIT_EXCEEDED
    console.error(err.status);     // status HTTP
    console.error(err.requestId);  // para suporte
  }
  throw err;
}

Tipos TypeScript

O SDK exporta tipos para respostas comuns:

import type { Workspace, VisibilitySummary } from '@mencionai/sdk';

Versão da API

O SDK tem como alvo a versão da API 2026-07-01. Consulte a referência da API ou a especificação OpenAPI para formatos completos de requisição/resposta.