index.d.ts

// Types for the Xproapi Node.js client. Field names follow the API's JSON exactly.

export const DEFAULT_BASE_URL: string;
export const VERSION: string;

export interface User {
  type: 'user';
  id: string;
  userName: string;
  name: string;
  url: string;
  description: string;
  profilePicture: string | null;
  followers: number;
  following: number;
  isBlueVerified: boolean;
  protected: boolean;
  unavailable: boolean;
}

export interface Tweet {
  type: 'tweet';
  id: string;
  url: string;
  text: string;
  source: string;
  retweetCount: number;
  replyCount: number;
  likeCount: number;
  quoteCount: number;
  viewCount: number;
  bookmarkCount: number;
  createdAt: string;
  lang: string;
  isReply: boolean;
  inReplyToId: string | null;
  conversationId: string | null;
  displayTextRange: number[] | null;
  inReplyToUserId: string | null;
  inReplyToUsername: string | null;
  author: User;
  entities: Record<string, unknown>;
  extendedEntities: Record<string, unknown>;
  quoted_tweet: Tweet | null;
  retweeted_tweet: Tweet | null;
  isLimitedReply: boolean;
}

export interface Article {
  author: User;
  replyCount: number;
  likeCount: number;
  quoteCount: number;
  viewCount: number;
  createdAt: string;
  title: string;
  preview_text: string;
  cover_media_img_url: string | null;
  contents: unknown[];
}

interface Envelope {
  status: 'success';
  message?: string;
  msg?: string;
}

interface Paged {
  has_next_page: boolean;
  /** Pass back as `cursor` for the next page; empty on the last page. */
  next_cursor: string;
}

export type UserResponse = Envelope & { data: User };
export type UsersResponse = Envelope & { users: User[] };
export type UsersPage = UsersResponse & Paged;
export type FollowersPage = Envelope & Paged & { followers: User[] };
export type FollowingsPage = Envelope & Paged & { followings: User[] };
export type TweetsResponse = Envelope & { tweets: Tweet[] };
export type TweetsPage = TweetsResponse & Paged;
export type RepliesPage = Envelope & Paged & { replies: Tweet[] };
export type ArticleResponse = Envelope & { article: Article };
export type AboutResponse = Envelope & { data: Record<string, unknown> };

export interface ClientOptions {
  /** From your panel → API → API keys. */
  apiKey: string;
  /** Defaults to https://xproapi.com/api. */
  baseUrl?: string;
  /** Milliseconds per request (default 30000). */
  timeout?: number;
  /** Retries for 429 / 502 / 503 / network errors (default 2, 0 = never). */
  maxRetries?: number;
  fetch?: typeof fetch;
  sleep?: (ms: number) => Promise<void>;
}

type Cursor = { cursor?: string };
type TimeRange = { sinceTime?: number; untilTime?: number };
type Tweeter = { userName: string; userId?: never } | { userId: string; userName?: never };

export interface PaginatedEndpoints {
  searchUsers: [{ query: string }, User];
  followers: [{ userName: string; pageSize?: number }, User];
  followings: [{ userName: string; pageSize?: number }, User];
  lastTweets: [Tweeter & { includeReplies?: boolean }, Tweet];
  tweetTimeline: [Tweeter & { includeReplies?: boolean; includeParentTweet?: boolean }, Tweet];
  mentions: [{ userName: string } & TimeRange, Tweet];
  advancedSearch: [{ query: string; queryType?: 'Latest' | 'Top' }, Tweet];
  replies: [{ tweetId: string } & TimeRange, Tweet];
  repliesV2: [{ tweetId: string; queryType?: 'Relevance' | 'Latest' | 'Likes' }, Tweet];
  quotes: [{ tweetId: string; includeReplies?: boolean } & TimeRange, Tweet];
  retweeters: [{ tweetId: string }, User];
  threadContext: [{ tweetId: string }, Tweet];
}

export class Xproapi {
  constructor(options: ClientOptions);

  /** Rate limit of the last response: your per-minute limit and requests left this minute. */
  rateLimit: { limit: number | null; remaining: number | null };

  userInfo(userName: string): Promise<UserResponse>;
  batchUserInfoByUsernames(userNames: string[]): Promise<UsersResponse>;
  userAbout(userName: string): Promise<AboutResponse>;
  searchUsers(query: string, options?: Cursor): Promise<UsersPage>;
  followers(userName: string, options?: Cursor & { pageSize?: number }): Promise<FollowersPage>;
  followings(userName: string, options?: Cursor & { pageSize?: number }): Promise<FollowingsPage>;
  lastTweets(options: Tweeter & Cursor & { includeReplies?: boolean }): Promise<TweetsPage>;
  tweetTimeline(options: Tweeter & Cursor & { includeReplies?: boolean; includeParentTweet?: boolean }): Promise<TweetsPage>;
  mentions(userName: string, options?: Cursor & TimeRange): Promise<TweetsPage>;

  tweetsByIds(tweetIds: string[]): Promise<TweetsResponse>;
  advancedSearch(query: string, options?: Cursor & { queryType?: 'Latest' | 'Top' }): Promise<TweetsPage>;
  replies(tweetId: string, options?: Cursor & TimeRange): Promise<RepliesPage>;
  repliesV2(tweetId: string, options?: Cursor & { queryType?: 'Relevance' | 'Latest' | 'Likes' }): Promise<TweetsPage>;
  quotes(tweetId: string, options?: Cursor & TimeRange & { includeReplies?: boolean }): Promise<TweetsPage>;
  retweeters(tweetId: string, options?: Cursor): Promise<UsersPage>;
  threadContext(tweetId: string, options?: Cursor): Promise<RepliesPage>;
  article(tweetId: string): Promise<ArticleResponse>;

  /** Every item of a paginated endpoint, following next_cursor. Each page is a separate (charged) request. */
  paginate<E extends keyof PaginatedEndpoints>(
    endpoint: E,
    params: PaginatedEndpoints[E][0],
    options?: { maxPages?: number },
  ): AsyncGenerator<PaginatedEndpoints[E][1], void, undefined>;

  /** Any GET endpoint under the base URL. */
  get<T = Record<string, unknown>>(path: string, params?: Record<string, string | number | boolean | null | undefined>): Promise<T>;
}

export default Xproapi;

export class XproapiError extends Error {
  /** HTTP status (0 for network errors). */
  status: number;
  /** The decoded JSON error body, when there was one. */
  body: { status: 'error'; error: number; message: string } | null;
  /** Seconds to wait before retrying (429 only). */
  retryAfter: number | null;
}
export class BadRequestError extends XproapiError {}
export class AuthenticationError extends XproapiError {}
export class InsufficientCreditsError extends XproapiError {}
export class PermissionDeniedError extends XproapiError {}
export class NotFoundError extends XproapiError {}
export class RateLimitError extends XproapiError {}
export class ServiceUnavailableError extends XproapiError {}