SDK TypeScript

El paquete @mencionai/sdk es la forma más sencilla de llamar a la API de MencionAI desde Node.js, funciones serverless o cualquier backend TypeScript/JavaScript.

Instalación

pnpm add @mencionai/sdk

npm install @mencionai/sdk

Inicio 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, 'menciones');
}

La URL base por defecto es https://www.mencionai.com/api/v1. Sobrescríbela si hace falta:

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

Obtener tu clave de API

Inicia sesión en MencionAI.
Ve a Configuración → Claves de API.
Crea una clave y guárdala en MENCIONAI_API_KEY (o tu gestor de secretos).

Nunca uses claves de API en código del navegador — llama a la API siempre desde el servidor.

Métodos

Organización y workspaces

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

Visibilidad

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

Scans

Encola un scan con una clave de idempotencia única (p. ej. UUID o tu propio id de deduplicación):

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 terminado:', job.status);

Webhooks

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

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

// Guarda endpoint.secret — solo se muestra al crear
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}`;

Manejo de errores

Las solicitudes fallidas lanzan MencionAiError:

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

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

Tipos TypeScript

El SDK exporta tipos para respuestas comunes:

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

Versión de la API

El SDK apunta a la versión de API 2026-07-01. Consulta la referencia de la API o la especificación OpenAPI para formas completas de solicitud/respuesta.