El cliente de Node

Una envoltura fina y tipada sobre los mismos endpoints HTTP. Nada de lo que hace es imposible con fetch; simplemente te ahorra volver a escribir las clases de error, los reintentos y la negociación de formato.

Instalación

npm install @xcrapcc/sdk

O con lo que uses de verdad:

pnpm add @xcrapcc/sdk
yarn add @xcrapcc/sdk
bun add @xcrapcc/sdk

Requiere · Node 18 o posterior. Sin dependencias en tiempo de ejecución: usa el fetch integrado.

Nunca una clave

Nada a lo que registrarse, nada que guardar en una variable de entorno, nada que rotar cuando alguien la sube al repositorio.
Tipado hasta el fondo

Declaraciones completas para cada método y cada forma de respuesta, de modo que un nombre de campo mal escrito es un subrayado rojo y no una sorpresa en ejecución.
Markdown incorporado

Una opción convierte cualquier respuesta en markdown listo para un prompt, con una estimación de lo que le costará a tu ventana de contexto.

Dos líneas hasta una publicación

No hay clave que pasar ni cliente que configurar. Lo construyes y lo llamas.

import { Xcrap } from '@xcrapcc/sdk';

const xcrap = new Xcrap();

const tweet = await xcrap.tweet('https://x.com/jack/status/20');
console.log(tweet.text);               // just setting up my twttr
console.log(tweet.metrics.likes);      // 308067

Markdown, con su coste en tokens

Todos los métodos de lectura aceptan una opción markdown. La respuesta vuelve como una cadena lista para un prompt, y el cliente anota cuántos tokens costará probablemente, para comprobar un presupuesto antes de gastarlo.

// Markdown, ready to drop into a prompt.
const md = await xcrap.tweet('https://x.com/jack/status/20', { markdown: true });

// How many tokens that will cost, before you spend them.
console.log(xcrap.lastMeta.markdownTokens);

Hilos y cronologías

Un hilo vuelve desenrollado y en orden, desde la primera publicación y no desde la última. Una cronología pagina con cursores para que no tengas que guardarlos.

const thread = await xcrap.thread(
  'https://x.com/naval/status/1002103360646823936',
);

console.log(thread.count);                      // 31
for (const post of thread.tweets) console.log(post.text);

Búsqueda, con los operadores de X

Pasa la consulta tal como la escribirías en X, operadores incluidos. Vuelve una página con el cursor de la siguiente. La búsqueda tiene el presupuesto más ajustado de todos los métodos: una consulta precisa vale más que cinco amplias.

const page = await xcrap.search('from:nasa mars', {
  feed: 'latest',          // or 'top', 'photos', 'videos'
  since: '2026-01-01',
});

for (const post of page.tweets) console.log(post.author.screen_name, post.text);

// The next page, when there is one.
if (page.next_cursor) await xcrap.search('from:nasa mars', { cursor: page.next_cursor });

Los errores son tipos, no códigos

Cada fallo es una clase que puedes capturar por su nombre. Un 404 es una publicación borrada o privada, un 429 lleva los segundos que faltan para que se reabra la ventana, y un fallo de red se distingue de una negativa.

import { Xcrap, XcrapNotFound, XcrapRateLimited } from '@xcrapcc/sdk';

try {
  await xcrap.tweet('https://x.com/jack/status/1');
} catch (error) {
  if (error instanceof XcrapNotFound) return null;
  if (error instanceof XcrapRateLimited) {
    // The client already knows when the window resets.
    await sleep(error.retryAfter * 1000);
  }
  throw error;
}

Todos los métodos

Todos aceptan un formato y una opción markdown, y todos devuelven las mismas formas que devuelve la API HTTP.

tweet(url, opts?): Una publicación, resuelta del todo: texto, autor, métricas, medios, encuesta y la publicación citada si la hay.
thread(url, opts?): Un hilo entero desde cualquiera de sus publicaciones, desenrollado en orden de publicación.
search(query, opts?): Posts que coinciden con una consulta — recientes, destacados, fotos o vídeos — dentro de un rango de fechas opcional.
replies(url, opts?): Una página de las respuestas directas a un post, primero las más gustadas o las más recientes.
user(handle, opts?): Un perfil: biografía, cifras, fecha de alta, verificación, ubicación y web.
userTweets(handle, opts?): Una página de publicaciones de una cuenta, con el cursor de la siguiente.
userHistory(handle, opts?): Hasta mil posts de una cuenta en una llamada, de más reciente a más antiguo, dentro de un rango de fechas opcional.
followers(handle, opts?): Una página de las cuentas que siguen a una cuenta.
following(handle, opts?): Una página de las cuentas que sigue una cuenta.
trends(opts?): Qué es tendencia, con el número de publicaciones cuando X lo da.
media(url, opts?): Cada archivo adjunto, en todos los bitrates que X codificó, como enlaces directos.
downloadMedia(url, opts?): Devuelve uno de esos archivos como bytes en lugar de como enlace.
bulk(urls, opts?): Hasta cincuenta publicaciones en una petición. Un enlace muerto solo hace fallar su entrada.

Cada parámetro, en la referencia de la API También hay un cliente de Python.