README.md

Xproapi Node.js SDK

The official Node.js SDK for Xproapi.com. A lightweight, dependency-free client with TypeScript types, designed to query public X (Twitter) profiles, track follower events, and detect network diffs without heavy enterprise API costs or streaming connection overhead.

---

Key Capabilities

• Follower Event Tracking: Fetch the latest follower pages, newest first, to detect new followers between runs.
• Profile & Graph Ingestion: Access public follower and following lists as typed JSON, with an async iterator over every page.
• Resilient Network Handling: Built-in rate limit (HTTP 429) backoff, automatic retries, and strict timeouts.
• Framework Agnostic: Works in plain Node.js, Express, NestJS, Next.js server code, or background workers.

---

Install

Requires Node 18+ (ES modules); no dependencies.

npm install ../xproapi-code-examples/xproapi-node

Usage

import { Xproapi } from 'xproapi';

const x = new Xproapi({ apiKey: process.env.XPROAPI_KEY });

const { data: user } = await x.userInfo('jack');
console.log(`${user.name} has ${user.followers} followers`);

// One page (up to 200)
const page = await x.followers('jack', { pageSize: 200 });
const next = await x.followers('jack', { cursor: page.next_cursor });

// Every page, capped at 5 requests
for await (const follower of x.paginate('followers', { userName: 'jack' }, { maxPages: 5 })) {
  console.log(follower.userName);
}

// Tweets
await x.lastTweets({ userName: 'jack', includeReplies: false });
await x.advancedSearch('from:jack min_faves:100', { queryType: 'Top' });
await x.tweetsByIds(['20', '1800000000000000000']);
await x.replies('https://x.com/jack/status/20'); // ids or links

Methods resolve to the API's JSON. Types (User, Tweet, FollowersPage…) are in src/index.d.ts.

Options

new Xproapi({
  apiKey: 'xp_...',
  baseUrl: 'https://xproapi.com/api', // default
  timeout: 30_000,                    // ms per request
  maxRetries: 2,                      // for 429 / 502 / 503 / network errors; 0 = off
  fetch,                              // custom fetch (proxies, tests)
});

Errors

import { InsufficientCreditsError, NotFoundError, RateLimitError, XproapiError } from 'xproapi';

try {
  await x.userInfo('someone');
} catch (error) {
  if (error instanceof NotFoundError) { /* no such user */ }
  else if (error instanceof InsufficientCreditsError) { /* top up; nothing was charged */ }
  else if (error instanceof RateLimitError) { await new Promise((r) => setTimeout(r, error.retryAfter * 1000)); }
  else if (error instanceof XproapiError) { console.error(error.status, error.message); }
  else throw error;
}

Rate limit

x.rateLimit; // { limit: 60, remaining: 57 } from the last response

Anything else

await x.get('/twitter/user/info', { userName: 'jack' }) calls any GET endpoint with the same auth, retries and errors.

Tests

npm test