@aura-score/tikhub-client

TypeScript client for TikHub API with support for Douyin (TikTok China), Weibo, and Xiaohongshu platforms.

Features

• 🚀 Full TypeScript support with complete type definitions
• 📦 Works in Node.js and modern browsers
• 🔄 Automatic retry logic with exponential backoff
• ⏱️ Configurable timeouts
• 🛡️ Built-in error handling
• 📝 Zod schema validation for all responses
• 🎯 Support for multiple Chinese social platforms:
  • Douyin (抖音): User profiles, videos, comments, hot searches
  • Weibo (微博): User info, posts, comments, AI search
  • Xiaohongshu (小红书): User profiles, notes, comments

Installation

npm install @aura-score/tikhub-client zod
# or
pnpm add @aura-score/tikhub-client zod
# or
yarn add @aura-score/tikhub-client zod

Note: zod is a peer dependency and must be installed separately.

Quick Start

import { TikHubClient } from '@aura-score/tikhub-client';

const client = new TikHubClient({
  apiKey: 'your-tikhub-api-key',
  // Optional configuration
  baseUrl: 'https://api.tikhub.io', // default
  timeoutMs: 30000, // 30 seconds (default)
  maxRetries: 3, // default
});

// Search Douyin users
const users = await client.searchDouyinUsers({
  keyword: '音乐',
  cursor: 0,
});

// Fetch Weibo user info
const weiboUser = await client.fetchWeiboUserInfo('123456789');

// Search Xiaohongshu notes
const notes = await client.searchXiaohongshuNotes({
  keyword: '美食',
  page: 1,
});

API Reference

Client Configuration

interface TikHubClientConfig {
  /** TikHub API key (required) */
  apiKey: string;
  /** TikHub API base URL (defaults to https://api.tikhub.io) */
  baseUrl?: string;
  /** Request timeout in milliseconds (defaults to 30000) */
  timeoutMs?: number;
  /** Maximum retry attempts (defaults to 3) */
  maxRetries?: number;
  /** Custom logger for debugging */
  logger?: {
    debug?: (message: string, context?: Record<string, unknown>) => void;
    warn?: (message: string, context?: Record<string, unknown>) => void;
    error?: (message: string, context?: Record<string, unknown>) => void;
  };
}

Douyin Methods

// Search users
client.searchDouyinUsers(params: SearchDouyinUsersRequest): Promise<SearchDouyinUsersResponse>

// Fetch user profile
client.fetchDouyinUserProfile(secUserId: string): Promise<DouyinUserProfileResponse>

// Fetch user videos
client.fetchDouyinUserPostVideos(secUserId: string, maxCursor?: number, count?: number): Promise<DouyinUserPostVideosResponse>

// Fetch video statistics (up to 50 videos)
client.fetchDouyinMultiVideoStatistics(awemeIds: string | string[]): Promise<DouyinVideoStatisticsResponse>

// Fetch video comments
client.fetchDouyinVideoComments(params: DouyinVideoCommentsRequest): Promise<DouyinVideoCommentsResponse>

// Search videos
client.searchDouyinVideosV2(params: DouyinVideoSearchV2Request): Promise<DouyinVideoSearchV2Response>

// Fetch hot search list
client.fetchDouyinHotSearchList(params?: DouyinHotSearchListRequest): Promise<DouyinHotSearchListResponse>

// Fetch music hot search list
client.fetchDouyinMusicHotSearchList(): Promise<DouyinMusicHotSearchListResponse>

Weibo Methods

// Fetch user info
client.fetchWeiboUserInfo(uid: string): Promise<WeiboUserInfoResponse>

// Fetch user posts
client.fetchWeiboUserPosts(uid: string, page?: number, feature?: number): Promise<WeiboUserPostsResponse>

// Fetch post comments
client.fetchWeiboPostComments(id: string, count?: number, maxId?: string): Promise<WeiboPostCommentsResponse>

// Video search
client.fetchWeiboVideoSearch(params: FetchWeiboVideoSearchRequest): Promise<WeiboVideoSearchResponse>

// Topic search
client.fetchWeiboTopicSearch(params: FetchWeiboTopicSearchRequest): Promise<WeiboTopicSearchResponse>

// AI-powered search
client.fetchWeiboAISearch(params: FetchWeiboAISearchRequest): Promise<WeiboAISearchResponse>

Xiaohongshu Methods

// Fetch user info
client.fetchXiaohongshuUserInfo(userId: string): Promise<AppUserInfoResponse>

// Search notes
client.searchXiaohongshuNotes(params: SearchNotesRequest): Promise<SearchNotesResponse>

// Search users
client.searchXiaohongshuUsers(params: SearchUsersRequest): Promise<SearchUsersResponse>

// Get note info
client.getXiaohongshuNoteInfoV2(params: GetNoteInfoV2Request): Promise<GetNoteInfoV2Response>

// Fetch note comments
client.fetchXiaohongshuNoteComments(params: XiaohongshuNoteCommentsRequest): Promise<XiaohongshuNoteCommentsResponse>

Error Handling

The client throws TikHubError for all API-related errors:

import { TikHubClient, TikHubError } from '@aura-score/tikhub-client';

try {
  const user = await client.fetchDouyinUserProfile('invalid-id');
} catch (error) {
  if (error instanceof TikHubError) {
    console.error('TikHub API Error:', error.message);
    console.error('Error Code:', error.code);
    console.error('Cause:', error.cause);
  }
}

Error Codes

• INVALID_CONFIG: Invalid client configuration
• INVALID_PARAMS: Invalid method parameters
• TIMEOUT: Request timed out
• BAD_REQUEST: API returned 4xx error
• SERVER_ERROR: API returned 5xx error
• NETWORK_ERROR: Network connectivity issue
• MAX_RETRIES_EXCEEDED: Exceeded maximum retry attempts

Advanced Usage

Custom Logger

const client = new TikHubClient({
  apiKey: 'your-api-key',
  logger: {
    debug: (msg, ctx) => console.log('[DEBUG]', msg, ctx),
    warn: (msg, ctx) => console.warn('[WARN]', msg, ctx),
    error: (msg, ctx) => console.error('[ERROR]', msg, ctx),
  },
});

Retry Configuration

const client = new TikHubClient({
  apiKey: 'your-api-key',
  maxRetries: 5, // Increase retry attempts
  timeoutMs: 60000, // Increase timeout to 60 seconds
});

Type Exports

All TypeScript types and Zod schemas are exported:

import type {
  // Douyin types
  DouyinUserProfileResponse,
  DouyinVideoStatisticsResponse,
  SearchDouyinUsersRequest,

  // Weibo types
  WeiboUserInfoResponse,
  WeiboUserPostsResponse,

  // Xiaohongshu types
  AppUserInfoResponse,
  SearchNotesRequest,
  SearchNotesResponse,
} from '@aura-score/tikhub-client';

License

MIT

Links

• TikHub API Documentation
• GitHub Repository