Lanza un blog, un registro de cambios y un centro de ayuda en una tarde con Kookee

Kookee es un backend de contenido: escribes entradas de blog, entradas del registro de cambios, artículos de ayuda, páginas y anuncios en un solo panel, y tu aplicación los obtiene como JSON y los muestra con tus propios componentes, en tu propio dominio. Esta guía va de un proyecto vacío a tres secciones de contenido publicadas, con el SDK de TypeScript. Si tu framework puede obtener JSON y renderizar en el servidor (Next.js, Astro, Nuxt, SvelteKit, TanStack Start), todo esto se aplica tal cual.

1. Crea un proyecto y obtén las credenciales

Regístrate (el plan gratuito no pide tarjeta de crédito e incluye los módulos de blog, registro de cambios y centro de ayuda), crea un proyecto y apunta dos credenciales:

• ID del proyecto: se puede exponer en el código del navegador; lee el contenido publicado, igual que la clave de API. Solo funciona mientras el portal alojado del proyecto esté habilitado; si no, la API responde 403 PORTAL_NOT_ENABLED.

• Clave de API: funciona en todos los proyectos, en tus servidores y en el navegador. Solo lee contenido publicado, y todo lo que llega a un navegador lo pueden ver los visitantes, así que restríngela a tus dominios con los orígenes permitidos del proyecto.

La regla práctica: apiKey en todas partes, restringida por orígenes permitidos siempre que llegue a un navegador; projectId en el código del navegador solo mientras el portal alojado siga activo.

Escribe ahora en el panel un borrador de entrada de blog, una entrada del registro de cambios y un artículo de ayuda, y publícalos: te conviene tener datos reales al otro lado de tu primera petición.

2. Instala e inicializa el SDK

npm install @kookee/sdk

import { Kookee } from '@kookee/sdk';

export const kookee = new Kookee({ apiKey: process.env.KOOKEE_API_KEY });

El SDK está pensado primero para TypeScript, no tiene dependencias y admite tree-shaking; todos los métodos de lectura aceptan un AbortSignal. Créalo una vez en un módulo compartido e impórtalo desde los loaders de tus rutas.

3. El blog: lista y detalle

Dos rutas. La página de lista:

const { data: posts } = await kookee.blog.list({ page: 1, limit: 10 });

Cada resumen trae título, slug, extracto, etiquetas y fechas: suficiente para las tarjetas. La página de detalle obtiene la entrada completa por su slug:

const post = await kookee.blog.getBySlug(slug);

Las respuestas de detalle incluyen el HTML del cuerpo ya renderizado y los campos SEO que configuraste en el editor, así que el head del documento sale de la misma petición: título, meta descripción, URL canónica a partir del slug, imagen OG. Si getBySlug no encuentra nada, devuelve un 404 de verdad.

Las páginas de etiquetas son la misma llamada de lista con tags: ['news']; un buscador es list({ search: query }); kookee.blog.getTags() te da la nube de etiquetas con sus recuentos.

4. El registro de cambios

La misma estructura, con categorías tipadas:

const { data: entries } = await kookee.changelog.list({ page: 1, limit: 20 });
const features = await kookee.changelog.list({ filter: { changelogType: 'feature' } });

Las entradas llevan un tipo (feature, fix, improvement, breaking, security, deprecated u other) y una versión opcional, así que tu interfaz puede mostrar insignias y filtros sin inventar una convención. Las reacciones son una sola llamada, si quieres una señal ligera sobre cada versión:

await kookee.changelog.react(entryId, { reactionType: 'fire', action: 'add' });

5. El centro de ayuda: categorías, artículos y búsqueda semántica

Tres peticiones cubren las rutas:

const categories = await kookee.help.categories();
const articles = await kookee.help.list({ category: 'getting-started' });
const article = await kookee.help.getBySlug('reset-your-password');

Lo que lo distingue es la búsqueda, que es semántica: busca por significado, no por palabras clave, y devuelve el fragmento que coincidió, para que puedas mostrar por qué aparece cada resultado:

const results = await kookee.help.search({ query: 'me cobraron dos veces este mes', limit: 5 });
// results[i].title, results[i].matchedChunk

Cuando tu base de artículos esté lista, el mismo contenido alimenta respuestas con IA: kookee.help.chat devuelve respuestas basadas en tus artículos, con sus fuentes, y chatStream emite deltas para una interfaz con streaming. Es la función de IA con consumo medido del plan gratuito (50 respuestas al mes para empezar) y no necesita ninguna integración extra: los artículos que acabas de publicar son el corpus.

6. Atajos para React, si es tu stack

@kookee/react envuelve todo lo anterior en hooks —useBlogPosts, useBlogPost, useChangelog, useHelpCategories, useHelpSearch (con debounce, se puede conectar directamente a un input)—, y cada uno devuelve { data, isLoading, error } con paginación mediante loadMore. Renderiza en el servidor con el loader de tu framework y pasa el resultado como initialData para que el primer pintado salga completo. Para el cuerpo, <EntryContent entry={post} /> renderiza el HTML de la entrada, con una hoja de estilos para los bloques de código que puedes importar en una capa de cascada de Tailwind.

Desde la versión 1.9.0, el paquete también incluye componentes renderizados en el servidor para las tres secciones; consulta Componentes de React para tu blog, registro de cambios y centro de ayuda.

7. Lo que obtienes sin escribir más código

• Un portal alojado en your-project.kookee.dev: el tablero de comentarios, la hoja de ruta, el registro de cambios y el centro de ayuda se publican en cuanto enciendes Activar el portal público en la página Portal público del proyecto. Sirve mientras tus propias rutas están en desarrollo (las páginas del portal llevan noindex, así que nunca compiten con tu dominio en los buscadores).

• Traducciones: todos los tipos de contenido aceptan un parámetro locale, con idiomas de respaldo por proyecto, para cuando tu sitio pase a tener varios idiomas.

• Comentarios y reacciones en todos los módulos, moderados desde el panel.

• Un servidor MCP, para que los agentes y asistentes de IA puedan buscar, leer y redactar tu contenido con un token personal para cada miembro del equipo, de solo lectura salvo que elijas otra cosa.

La tarde, desglosada

Siendo realistas: configurar el proyecto y el primer contenido, media hora; las rutas del blog, una hora; el registro de cambios, media hora; el centro de ayuda con búsqueda, una o dos horas; conectar los metadatos del head, una hora. Las 100 000 peticiones a la API al mes del plan gratuito cubren con holgura el tráfico renderizado en el servidor de un sitio pequeño, y no pagas nada hasta que se te quede corto.

El patrón que hace que esto sea rápido es la razón de ser del producto: Kookee se encarga de la edición, el almacenamiento, la búsqueda y la entrega; tú te encargas de dos o tres rutas ligeras por sección, hechas con los componentes que ya tienes. Crea el proyecto, publica una entrada de prueba y haz la primera llamada a list: lo demás sale de ahí.