tiktok-live-api 1.4.6 → 1.4.7

package/README.md

@@ -185,6 +185,54 @@ client.on('chat', (e) => console.log(e.comment));
 client.connect();
 ```
 
+## REST API - leaderboards, recruiting, profiles, gifts
+
+The WebSocket client streams live events. For everything else - leaderboards,
+gaming ranks, recruiting, live status, gift catalogs, profiles - use the
+`TikTool` REST client. One method per endpoint, fully promise-based.
+
+```typescript
+import { TikTool } from 'tiktok-live-api';
+
+const api = new TikTool({ apiKey: 'YOUR_KEY' });
+
+// Live status (single + bulk)
+await api.liveStatus('charlidamelio');
+await api.bulkLiveCheck(['user1', 'user2', 'user3']);
+
+// Leaderboards + rankings
+await api.leaderboard({ region: 'US+' });
+await api.ranklistGaming('US+');
+await api.regionMovers('US+');           // entered top today, below cutoff now
+
+// Recruiting (Global Agency) - find eligible creators
+await api.eligibleCreators({ region: 'US+', limit: 50, min_score: 1000 });
+
+// Profiles + gifts
+await api.profileInfo('khaby.lame');
+await api.userProfile('khaby.lame');
+await api.giftsByCountry('US');
+```
+
+Tier gating is enforced server-side: a call above your tier throws a
+`TikToolError` with `status === 403`. Any endpoint not yet wrapped is reachable
+via `api.request('/webcast/...', { query })`.
+
+```typescript
+import { TikTool, TikToolError } from 'tiktok-live-api';
+try {
+  await api.eligibleCreators({ region: 'US+' });
+} catch (e) {
+  if (e instanceof TikToolError && e.status === 403) {
+    console.log('Upgrade required:', e.message);
+  }
+}
+```
+
+Method groups: signing/connection, live status, rankings/leaderboards, gifts,
+user/profile, content/feed, live analytics, moderation, CAPTCHA solver, captions.
+See [the full endpoint + tier matrix](https://tik.tools/docs).
+
 ## Events (54 v3 event types)
 
 Every event is dispatched by name. `client.on('chat', e => ...)` is fully typed end-to-end. Each event payload extends `BaseEvent` (`type`, `timestamp`, `msgId`, optional `protoVersion: 1 | 2 | 3`).

package/dist/index.d.mts

@@ -326,6 +326,110 @@ declare class TikTokLive {
     private _maybeReconnect;
 }
 
+/**
+ * TikTool REST client - typed methods for every customer-facing tik.tools
+ * REST endpoint. Pairs with the {@link TikTokLive} WebSocket client.
+ *
+ * @example
+ * ```typescript
+ * import { TikTool } from 'tiktok-live-api';
+ *
+ * const api = new TikTool({ apiKey: 'YOUR_KEY' });
+ *
+ * const live = await api.isLive('username');
+ * const board = await api.leaderboard({ region: 'US+' });
+ * const recruits = await api.eligibleCreators({ region: 'US+', limit: 50 });
+ * ```
+ *
+ * Uses the global `fetch` (Node 18+ or any browser).
+ */
+interface TikToolOptions {
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://api.tik.tools */
+    baseUrl?: string;
+}
+/** Thrown when an endpoint returns a non-2xx status. `body` holds the parsed error payload. */
+declare class TikToolError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+type Query = Record<string, string | number | boolean | undefined | null>;
+interface RequestOpts {
+    method?: 'GET' | 'POST';
+    query?: Query;
+    body?: unknown;
+}
+declare class TikTool {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: TikToolOptions);
+    /** Low-level request. Use the named methods below; this is exposed for endpoints not yet wrapped. */
+    request<T = any>(path: string, opts?: RequestOpts): Promise<T>;
+    /**
+     * Creator-identifier query params. The API is inconsistent about whether an
+     * endpoint reads `unique_id`, `username`, or `uniqueId`, so we send all three;
+     * unused ones are ignored server-side.
+     */
+    private uid;
+    signUrl(url: string): Promise<any>;
+    signWebsocket(body: Record<string, unknown>): Promise<any>;
+    wsCredentials(uniqueId: string): Promise<any>;
+    connectionMode(uniqueId: string): Promise<any>;
+    checkAlive(uniqueId: string): Promise<any>;
+    rateLimits(): Promise<any>;
+    wsSessions(): Promise<any>;
+    jwt(body?: Record<string, unknown>): Promise<any>;
+    isLive(uniqueId: string): Promise<any>;
+    liveStatus(uniqueId: string): Promise<any>;
+    bulkLiveCheck(usernames: string[]): Promise<any>;
+    liveCounts(region?: string): Promise<any>;
+    roomId(uniqueId: string): Promise<any>;
+    roomInfo(uniqueId: string): Promise<any>;
+    roomCover(uniqueId: string): Promise<any>;
+    roomVideo(uniqueId: string): Promise<any>;
+    rankings(query?: Query): Promise<any>;
+    ranklist(query?: Query): Promise<any>;
+    ranklistRegional(region: string): Promise<any>;
+    ranklistGaming(region: string): Promise<any>;
+    gamingMovers(region: string): Promise<any>;
+    regionMovers(region: string): Promise<any>;
+    leaderboard(query: {
+        region: string;
+    } & Query): Promise<any>;
+    eligibleCreators(query: {
+        region?: string;
+        page?: number;
+        limit?: number;
+        min_score?: number;
+    } & Query): Promise<any>;
+    giftInfo(query?: Query): Promise<any>;
+    giftGallery(query?: Query): Promise<any>;
+    giftsByCountry(country: string): Promise<any>;
+    lookupUsername(uniqueId: string): Promise<any>;
+    profileInfo(uniqueId: string): Promise<any>;
+    resolveUserIds(usernames: string[]): Promise<any>;
+    userProfile(uniqueId: string): Promise<any>;
+    userVideos(uniqueId: string, query?: Query): Promise<any>;
+    userFollowers(uniqueId: string, query?: Query): Promise<any>;
+    userFollowing(uniqueId: string, query?: Query): Promise<any>;
+    userLikes(uniqueId: string, query?: Query): Promise<any>;
+    userEarnings(uniqueId: string): Promise<any>;
+    hashtagList(query?: Query): Promise<any>;
+    fetch(body: Record<string, unknown>): Promise<any>;
+    feed(query?: Query): Promise<any>;
+    chat(uniqueId: string, query?: Query): Promise<any>;
+    analyticsVideoList(query?: Query): Promise<any>;
+    analyticsVideoDetail(query?: Query): Promise<any>;
+    analyticsUserInteractions(query?: Query): Promise<any>;
+    moderationMutes(uniqueId: string): Promise<any>;
+    moderationBans(uniqueId: string): Promise<any>;
+    solvePuzzle(body: Record<string, unknown>): Promise<any>;
+    solveRotate(body: Record<string, unknown>): Promise<any>;
+    solveShapes(body: Record<string, unknown>): Promise<any>;
+    captionsCredits(): Promise<any>;
+}
+
 /**
  * TikTokCaptions - Real-time AI speech-to-text for TikTok LIVE streams.
  *
@@ -431,4 +535,4 @@ declare class TikTokCaptions {
     disconnect(): void;
 }
 
-export { type BattleEvent, type CaptionEvent, type ChatEvent, type ConnectedEvent, type CreditsEvent, type DisconnectedEvent, type ErrorEvent, type GiftEvent, type LikeEvent, type MemberEvent, type RoomUserSeqEvent, type SocialEvent, TikTokCaptions, type TikTokCaptionsEventMap, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEventMap, type TikTokLiveOptions, type TikTokUser, type TranslationEvent };
+export { type BattleEvent, type CaptionEvent, type ChatEvent, type ConnectedEvent, type CreditsEvent, type DisconnectedEvent, type ErrorEvent, type GiftEvent, type LikeEvent, type MemberEvent, type RoomUserSeqEvent, type SocialEvent, TikTokCaptions, type TikTokCaptionsEventMap, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEventMap, type TikTokLiveOptions, type TikTokUser, TikTool, TikToolError, type TikToolOptions, type TranslationEvent };

package/dist/index.d.ts

@@ -326,6 +326,110 @@ declare class TikTokLive {
     private _maybeReconnect;
 }
 
+/**
+ * TikTool REST client - typed methods for every customer-facing tik.tools
+ * REST endpoint. Pairs with the {@link TikTokLive} WebSocket client.
+ *
+ * @example
+ * ```typescript
+ * import { TikTool } from 'tiktok-live-api';
+ *
+ * const api = new TikTool({ apiKey: 'YOUR_KEY' });
+ *
+ * const live = await api.isLive('username');
+ * const board = await api.leaderboard({ region: 'US+' });
+ * const recruits = await api.eligibleCreators({ region: 'US+', limit: 50 });
+ * ```
+ *
+ * Uses the global `fetch` (Node 18+ or any browser).
+ */
+interface TikToolOptions {
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://api.tik.tools */
+    baseUrl?: string;
+}
+/** Thrown when an endpoint returns a non-2xx status. `body` holds the parsed error payload. */
+declare class TikToolError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+type Query = Record<string, string | number | boolean | undefined | null>;
+interface RequestOpts {
+    method?: 'GET' | 'POST';
+    query?: Query;
+    body?: unknown;
+}
+declare class TikTool {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: TikToolOptions);
+    /** Low-level request. Use the named methods below; this is exposed for endpoints not yet wrapped. */
+    request<T = any>(path: string, opts?: RequestOpts): Promise<T>;
+    /**
+     * Creator-identifier query params. The API is inconsistent about whether an
+     * endpoint reads `unique_id`, `username`, or `uniqueId`, so we send all three;
+     * unused ones are ignored server-side.
+     */
+    private uid;
+    signUrl(url: string): Promise<any>;
+    signWebsocket(body: Record<string, unknown>): Promise<any>;
+    wsCredentials(uniqueId: string): Promise<any>;
+    connectionMode(uniqueId: string): Promise<any>;
+    checkAlive(uniqueId: string): Promise<any>;
+    rateLimits(): Promise<any>;
+    wsSessions(): Promise<any>;
+    jwt(body?: Record<string, unknown>): Promise<any>;
+    isLive(uniqueId: string): Promise<any>;
+    liveStatus(uniqueId: string): Promise<any>;
+    bulkLiveCheck(usernames: string[]): Promise<any>;
+    liveCounts(region?: string): Promise<any>;
+    roomId(uniqueId: string): Promise<any>;
+    roomInfo(uniqueId: string): Promise<any>;
+    roomCover(uniqueId: string): Promise<any>;
+    roomVideo(uniqueId: string): Promise<any>;
+    rankings(query?: Query): Promise<any>;
+    ranklist(query?: Query): Promise<any>;
+    ranklistRegional(region: string): Promise<any>;
+    ranklistGaming(region: string): Promise<any>;
+    gamingMovers(region: string): Promise<any>;
+    regionMovers(region: string): Promise<any>;
+    leaderboard(query: {
+        region: string;
+    } & Query): Promise<any>;
+    eligibleCreators(query: {
+        region?: string;
+        page?: number;
+        limit?: number;
+        min_score?: number;
+    } & Query): Promise<any>;
+    giftInfo(query?: Query): Promise<any>;
+    giftGallery(query?: Query): Promise<any>;
+    giftsByCountry(country: string): Promise<any>;
+    lookupUsername(uniqueId: string): Promise<any>;
+    profileInfo(uniqueId: string): Promise<any>;
+    resolveUserIds(usernames: string[]): Promise<any>;
+    userProfile(uniqueId: string): Promise<any>;
+    userVideos(uniqueId: string, query?: Query): Promise<any>;
+    userFollowers(uniqueId: string, query?: Query): Promise<any>;
+    userFollowing(uniqueId: string, query?: Query): Promise<any>;
+    userLikes(uniqueId: string, query?: Query): Promise<any>;
+    userEarnings(uniqueId: string): Promise<any>;
+    hashtagList(query?: Query): Promise<any>;
+    fetch(body: Record<string, unknown>): Promise<any>;
+    feed(query?: Query): Promise<any>;
+    chat(uniqueId: string, query?: Query): Promise<any>;
+    analyticsVideoList(query?: Query): Promise<any>;
+    analyticsVideoDetail(query?: Query): Promise<any>;
+    analyticsUserInteractions(query?: Query): Promise<any>;
+    moderationMutes(uniqueId: string): Promise<any>;
+    moderationBans(uniqueId: string): Promise<any>;
+    solvePuzzle(body: Record<string, unknown>): Promise<any>;
+    solveRotate(body: Record<string, unknown>): Promise<any>;
+    solveShapes(body: Record<string, unknown>): Promise<any>;
+    captionsCredits(): Promise<any>;
+}
+
 /**
  * TikTokCaptions - Real-time AI speech-to-text for TikTok LIVE streams.
  *
@@ -431,4 +535,4 @@ declare class TikTokCaptions {
     disconnect(): void;
 }
 
-export { type BattleEvent, type CaptionEvent, type ChatEvent, type ConnectedEvent, type CreditsEvent, type DisconnectedEvent, type ErrorEvent, type GiftEvent, type LikeEvent, type MemberEvent, type RoomUserSeqEvent, type SocialEvent, TikTokCaptions, type TikTokCaptionsEventMap, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEventMap, type TikTokLiveOptions, type TikTokUser, type TranslationEvent };
+export { type BattleEvent, type CaptionEvent, type ChatEvent, type ConnectedEvent, type CreditsEvent, type DisconnectedEvent, type ErrorEvent, type GiftEvent, type LikeEvent, type MemberEvent, type RoomUserSeqEvent, type SocialEvent, TikTokCaptions, type TikTokCaptionsEventMap, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEventMap, type TikTokLiveOptions, type TikTokUser, TikTool, TikToolError, type TikToolOptions, type TranslationEvent };

package/dist/index.js

@@ -31,7 +31,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   TikTokCaptions: () => TikTokCaptions,
-  TikTokLive: () => TikTokLive
+  TikTokLive: () => TikTokLive,
+  TikTool: () => TikTool,
+  TikToolError: () => TikToolError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -177,6 +179,216 @@ var TikTokLive = class {
   }
 };
 
+// src/rest.ts
+var REST_BASE = "https://api.tik.tools";
+var TikToolError = class extends Error {
+  constructor(status, body) {
+    const msg = body && typeof body === "object" && "error" in body ? String(body.error) : `Request failed with status ${status}`;
+    super(msg);
+    this.name = "TikToolError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var TikTool = class {
+  constructor(options) {
+    if (!options?.apiKey) throw new Error("TikTool requires an apiKey");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? REST_BASE).replace(/\/$/, "");
+  }
+  /** Low-level request. Use the named methods below; this is exposed for endpoints not yet wrapped. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- API boundary
+  async request(path, opts = {}) {
+    const url = new URL(this.baseUrl + path);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = { "x-api-key": this.apiKey };
+    if (opts.body !== void 0) headers["content-type"] = "application/json";
+    const res = await fetch(url.toString(), {
+      method: opts.method ?? "GET",
+      headers,
+      body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+    });
+    const text = await res.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = text;
+    }
+    if (!res.ok) throw new TikToolError(res.status, data);
+    return data;
+  }
+  /**
+   * Creator-identifier query params. The API is inconsistent about whether an
+   * endpoint reads `unique_id`, `username`, or `uniqueId`, so we send all three;
+   * unused ones are ignored server-side.
+   */
+  uid(uniqueId) {
+    return { unique_id: uniqueId, username: uniqueId, uniqueId };
+  }
+  // --- Signing / connection ---
+  signUrl(url) {
+    return this.request("/webcast/sign_url", { method: "POST", body: { url } });
+  }
+  signWebsocket(body) {
+    return this.request("/webcast/sign_websocket", { method: "POST", body });
+  }
+  wsCredentials(uniqueId) {
+    return this.request("/webcast/ws_credentials", { query: this.uid(uniqueId) });
+  }
+  connectionMode(uniqueId) {
+    return this.request("/webcast/connection_mode", { query: this.uid(uniqueId) });
+  }
+  checkAlive(uniqueId) {
+    return this.request("/webcast/check_alive", { query: this.uid(uniqueId) });
+  }
+  rateLimits() {
+    return this.request("/webcast/rate_limits");
+  }
+  wsSessions() {
+    return this.request("/webcast/ws_sessions");
+  }
+  jwt(body) {
+    return this.request("/authentication/jwt", { method: "POST", body: body ?? {} });
+  }
+  // --- Live status ---
+  isLive(uniqueId) {
+    return this.request("/webcast/is_live", { query: this.uid(uniqueId) });
+  }
+  liveStatus(uniqueId) {
+    return this.request("/webcast/live_status", { query: this.uid(uniqueId) });
+  }
+  bulkLiveCheck(usernames) {
+    return this.request("/webcast/bulk_live_check", { method: "POST", body: { usernames } });
+  }
+  liveCounts(region) {
+    return this.request("/webcast/live_counts", { query: { region } });
+  }
+  roomId(uniqueId) {
+    return this.request("/webcast/room_id", { query: this.uid(uniqueId) });
+  }
+  roomInfo(uniqueId) {
+    return this.request("/webcast/room_info", { query: this.uid(uniqueId) });
+  }
+  roomCover(uniqueId) {
+    return this.request("/webcast/room_cover", { query: this.uid(uniqueId) });
+  }
+  roomVideo(uniqueId) {
+    return this.request("/webcast/room_video", { query: this.uid(uniqueId) });
+  }
+  // --- Rankings / leaderboards ---
+  rankings(query) {
+    return this.request("/webcast/rankings", { query });
+  }
+  ranklist(query) {
+    return this.request("/webcast/ranklist", { query });
+  }
+  ranklistRegional(region) {
+    return this.request("/webcast/ranklist/regional", { query: { region } });
+  }
+  ranklistGaming(region) {
+    return this.request("/webcast/ranklist/gaming", { query: { region } });
+  }
+  gamingMovers(region) {
+    return this.request("/webcast/ranklist/gaming_movers", { query: { region } });
+  }
+  regionMovers(region) {
+    return this.request("/webcast/ranklist/region_movers", { query: { region } });
+  }
+  leaderboard(query) {
+    return this.request("/webcast/leaderboard", { query });
+  }
+  eligibleCreators(query) {
+    return this.request("/webcast/eligible_creators", { query });
+  }
+  // --- Gifts ---
+  giftInfo(query) {
+    return this.request("/webcast/gift_info", { query });
+  }
+  giftGallery(query) {
+    return this.request("/webcast/gift_gallery", { query });
+  }
+  giftsByCountry(country) {
+    return this.request("/webcast/gifts_by_country", { query: { country } });
+  }
+  // --- User / profile ---
+  lookupUsername(uniqueId) {
+    return this.request("/webcast/lookup_username", { query: this.uid(uniqueId) });
+  }
+  profileInfo(uniqueId) {
+    return this.request("/webcast/profile_info", { query: this.uid(uniqueId) });
+  }
+  resolveUserIds(usernames) {
+    return this.request("/webcast/resolve_user_ids", { method: "POST", body: { usernames } });
+  }
+  userProfile(uniqueId) {
+    return this.request("/webcast/user_profile", { query: this.uid(uniqueId) });
+  }
+  userVideos(uniqueId, query) {
+    return this.request("/webcast/user_videos", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userFollowers(uniqueId, query) {
+    return this.request("/webcast/user_followers", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userFollowing(uniqueId, query) {
+    return this.request("/webcast/user_following", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userLikes(uniqueId, query) {
+    return this.request("/webcast/user_likes", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userEarnings(uniqueId) {
+    return this.request("/webcast/user_earnings", { query: this.uid(uniqueId) });
+  }
+  // --- Content / feed ---
+  hashtagList(query) {
+    return this.request("/webcast/hashtag_list", { query });
+  }
+  fetch(body) {
+    return this.request("/webcast/fetch", { method: "POST", body });
+  }
+  feed(query) {
+    return this.request("/webcast/feed", { query });
+  }
+  chat(uniqueId, query) {
+    return this.request("/webcast/chat", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  // --- Live analytics ---
+  analyticsVideoList(query) {
+    return this.request("/webcast/live_analytics/video_list", { query });
+  }
+  analyticsVideoDetail(query) {
+    return this.request("/webcast/live_analytics/video_detail", { query });
+  }
+  analyticsUserInteractions(query) {
+    return this.request("/webcast/live_analytics/user_interactions", { query });
+  }
+  // --- Moderation ---
+  moderationMutes(uniqueId) {
+    return this.request("/webcast/moderation/mutes", { query: this.uid(uniqueId) });
+  }
+  moderationBans(uniqueId) {
+    return this.request("/webcast/moderation/bans", { query: this.uid(uniqueId) });
+  }
+  // --- CAPTCHA solver (Pro+) ---
+  solvePuzzle(body) {
+    return this.request("/captcha/solve/puzzle", { method: "POST", body });
+  }
+  solveRotate(body) {
+    return this.request("/captcha/solve/rotate", { method: "POST", body });
+  }
+  solveShapes(body) {
+    return this.request("/captcha/solve/shapes", { method: "POST", body });
+  }
+  // --- Captions ---
+  captionsCredits() {
+    return this.request("/captions/credits");
+  }
+};
+
 // src/captions.ts
 var import_ws2 = __toESM(require("ws"));
 var CAPTIONS_BASE = "wss://api.tik.tools/captions";
@@ -287,5 +499,7 @@ var TikTokCaptions = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TikTokCaptions,
-  TikTokLive
+  TikTokLive,
+  TikTool,
+  TikToolError
 });

package/dist/index.mjs

@@ -140,6 +140,216 @@ var TikTokLive = class {
   }
 };
 
+// src/rest.ts
+var REST_BASE = "https://api.tik.tools";
+var TikToolError = class extends Error {
+  constructor(status, body) {
+    const msg = body && typeof body === "object" && "error" in body ? String(body.error) : `Request failed with status ${status}`;
+    super(msg);
+    this.name = "TikToolError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var TikTool = class {
+  constructor(options) {
+    if (!options?.apiKey) throw new Error("TikTool requires an apiKey");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? REST_BASE).replace(/\/$/, "");
+  }
+  /** Low-level request. Use the named methods below; this is exposed for endpoints not yet wrapped. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- API boundary
+  async request(path, opts = {}) {
+    const url = new URL(this.baseUrl + path);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = { "x-api-key": this.apiKey };
+    if (opts.body !== void 0) headers["content-type"] = "application/json";
+    const res = await fetch(url.toString(), {
+      method: opts.method ?? "GET",
+      headers,
+      body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+    });
+    const text = await res.text();
+    let data;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      data = text;
+    }
+    if (!res.ok) throw new TikToolError(res.status, data);
+    return data;
+  }
+  /**
+   * Creator-identifier query params. The API is inconsistent about whether an
+   * endpoint reads `unique_id`, `username`, or `uniqueId`, so we send all three;
+   * unused ones are ignored server-side.
+   */
+  uid(uniqueId) {
+    return { unique_id: uniqueId, username: uniqueId, uniqueId };
+  }
+  // --- Signing / connection ---
+  signUrl(url) {
+    return this.request("/webcast/sign_url", { method: "POST", body: { url } });
+  }
+  signWebsocket(body) {
+    return this.request("/webcast/sign_websocket", { method: "POST", body });
+  }
+  wsCredentials(uniqueId) {
+    return this.request("/webcast/ws_credentials", { query: this.uid(uniqueId) });
+  }
+  connectionMode(uniqueId) {
+    return this.request("/webcast/connection_mode", { query: this.uid(uniqueId) });
+  }
+  checkAlive(uniqueId) {
+    return this.request("/webcast/check_alive", { query: this.uid(uniqueId) });
+  }
+  rateLimits() {
+    return this.request("/webcast/rate_limits");
+  }
+  wsSessions() {
+    return this.request("/webcast/ws_sessions");
+  }
+  jwt(body) {
+    return this.request("/authentication/jwt", { method: "POST", body: body ?? {} });
+  }
+  // --- Live status ---
+  isLive(uniqueId) {
+    return this.request("/webcast/is_live", { query: this.uid(uniqueId) });
+  }
+  liveStatus(uniqueId) {
+    return this.request("/webcast/live_status", { query: this.uid(uniqueId) });
+  }
+  bulkLiveCheck(usernames) {
+    return this.request("/webcast/bulk_live_check", { method: "POST", body: { usernames } });
+  }
+  liveCounts(region) {
+    return this.request("/webcast/live_counts", { query: { region } });
+  }
+  roomId(uniqueId) {
+    return this.request("/webcast/room_id", { query: this.uid(uniqueId) });
+  }
+  roomInfo(uniqueId) {
+    return this.request("/webcast/room_info", { query: this.uid(uniqueId) });
+  }
+  roomCover(uniqueId) {
+    return this.request("/webcast/room_cover", { query: this.uid(uniqueId) });
+  }
+  roomVideo(uniqueId) {
+    return this.request("/webcast/room_video", { query: this.uid(uniqueId) });
+  }
+  // --- Rankings / leaderboards ---
+  rankings(query) {
+    return this.request("/webcast/rankings", { query });
+  }
+  ranklist(query) {
+    return this.request("/webcast/ranklist", { query });
+  }
+  ranklistRegional(region) {
+    return this.request("/webcast/ranklist/regional", { query: { region } });
+  }
+  ranklistGaming(region) {
+    return this.request("/webcast/ranklist/gaming", { query: { region } });
+  }
+  gamingMovers(region) {
+    return this.request("/webcast/ranklist/gaming_movers", { query: { region } });
+  }
+  regionMovers(region) {
+    return this.request("/webcast/ranklist/region_movers", { query: { region } });
+  }
+  leaderboard(query) {
+    return this.request("/webcast/leaderboard", { query });
+  }
+  eligibleCreators(query) {
+    return this.request("/webcast/eligible_creators", { query });
+  }
+  // --- Gifts ---
+  giftInfo(query) {
+    return this.request("/webcast/gift_info", { query });
+  }
+  giftGallery(query) {
+    return this.request("/webcast/gift_gallery", { query });
+  }
+  giftsByCountry(country) {
+    return this.request("/webcast/gifts_by_country", { query: { country } });
+  }
+  // --- User / profile ---
+  lookupUsername(uniqueId) {
+    return this.request("/webcast/lookup_username", { query: this.uid(uniqueId) });
+  }
+  profileInfo(uniqueId) {
+    return this.request("/webcast/profile_info", { query: this.uid(uniqueId) });
+  }
+  resolveUserIds(usernames) {
+    return this.request("/webcast/resolve_user_ids", { method: "POST", body: { usernames } });
+  }
+  userProfile(uniqueId) {
+    return this.request("/webcast/user_profile", { query: this.uid(uniqueId) });
+  }
+  userVideos(uniqueId, query) {
+    return this.request("/webcast/user_videos", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userFollowers(uniqueId, query) {
+    return this.request("/webcast/user_followers", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userFollowing(uniqueId, query) {
+    return this.request("/webcast/user_following", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userLikes(uniqueId, query) {
+    return this.request("/webcast/user_likes", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  userEarnings(uniqueId) {
+    return this.request("/webcast/user_earnings", { query: this.uid(uniqueId) });
+  }
+  // --- Content / feed ---
+  hashtagList(query) {
+    return this.request("/webcast/hashtag_list", { query });
+  }
+  fetch(body) {
+    return this.request("/webcast/fetch", { method: "POST", body });
+  }
+  feed(query) {
+    return this.request("/webcast/feed", { query });
+  }
+  chat(uniqueId, query) {
+    return this.request("/webcast/chat", { query: { ...this.uid(uniqueId), ...query } });
+  }
+  // --- Live analytics ---
+  analyticsVideoList(query) {
+    return this.request("/webcast/live_analytics/video_list", { query });
+  }
+  analyticsVideoDetail(query) {
+    return this.request("/webcast/live_analytics/video_detail", { query });
+  }
+  analyticsUserInteractions(query) {
+    return this.request("/webcast/live_analytics/user_interactions", { query });
+  }
+  // --- Moderation ---
+  moderationMutes(uniqueId) {
+    return this.request("/webcast/moderation/mutes", { query: this.uid(uniqueId) });
+  }
+  moderationBans(uniqueId) {
+    return this.request("/webcast/moderation/bans", { query: this.uid(uniqueId) });
+  }
+  // --- CAPTCHA solver (Pro+) ---
+  solvePuzzle(body) {
+    return this.request("/captcha/solve/puzzle", { method: "POST", body });
+  }
+  solveRotate(body) {
+    return this.request("/captcha/solve/rotate", { method: "POST", body });
+  }
+  solveShapes(body) {
+    return this.request("/captcha/solve/shapes", { method: "POST", body });
+  }
+  // --- Captions ---
+  captionsCredits() {
+    return this.request("/captions/credits");
+  }
+};
+
 // src/captions.ts
 import WebSocket2 from "ws";
 var CAPTIONS_BASE = "wss://api.tik.tools/captions";
@@ -249,5 +459,7 @@ var TikTokCaptions = class {
 };
 export {
   TikTokCaptions,
-  TikTokLive
+  TikTokLive,
+  TikTool,
+  TikToolError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-live-api",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Unofficial TikTok LIVE API Client - Real-time chat, gifts, viewers, battles, and AI live captions from any TikTok livestream. Managed WebSocket API with 99.9% uptime.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",