twitterapi-io-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jorvixsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# TwitterAPI.io TypeScript Client
+
+A TypeScript client library for the [TwitterAPI.io](https://docs.twitterapi.io) API.
+
+## Installation
+
+```bash
+npm install twitterapi-io-client
+```
+
+## Usage
+
+```typescript
+import { TwitterAPIIOClient } from 'twitterapi-io-client';
+
+const client = new TwitterAPIIOClient({
+  apiKey: 'your-api-key'
+});
+```
+
+## Supported Endpoints
+
+### ✅ User Endpoint
+
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| Get User Profile About | `GET /twitter/user_about` | ✅ Supported | `client.users.getUserProfileAbout(userName)` |
+| Get User Info | `GET /twitter/user/info` | ✅ Supported | `client.users.getUserInfo(userName)` |
+| Get User Last Tweets | `GET /twitter/user/latest_tweets` | ✅ Supported | `client.users.getUserLatestTweets(userId?, userName?, cursor?, pageSize?, includeReplies?)` |
+| Get User Followers | `GET /twitter/user/followers` | ✅ Supported | `client.users.getUserFollowers(userName, cursor?, pageSize?)` |
+| Get User Followings | `GET /twitter/user/followings` | ✅ Supported | `client.users.getUserFollowings(userName, cursor?, pageSize?)` |
+| Get User Mentions | `GET /twitter/user/mentions` | ✅ Supported | `client.users.getUserMentions(username, sinceTime, untilTime, cursor?)` |
+| Check Follow Relationship | `GET /twitter/user/check_follow_relationship` | ✅ Supported | `client.users.checkFollowRelationship(sourceUserName, targetUserName)` |
+| Search user by keyword | `GET /twitter/user/search` | ✅ Supported | `client.users.searchUserByKeyword(query, cursor?)` |
+| Get User Verified Followers | `GET /twitter/user/verifiedFollowers` | ✅ Supported | `client.users.getUserVerifiedFollowers(userId, cursor?)` |
+| Batch Get User Info By UserIds | `GET /twitter/user/batch` | ❌ Not Supported | - |
+
+### ✅ List Endpoint
+
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| Get List Followers | `GET /twitter/list/followers` | ✅ Supported | `client.list.getListFollowers(listId, cursor?)` |
+| Get List Members | `GET /twitter/list/members` | ✅ Supported | `client.list.getListMembers(listId, cursor?)` |
+
+### ✅ My Endpoint
+
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| Get My Account Info | `GET /oapi/my/info` | ✅ Supported | `client.myEndpoint.getMyAccountInfo()` |
+
+### ✅ Communities Endpoint
+
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| Get Community Info By Id | `GET /twitter/community/info` | ✅ Supported | `client.communities.getCommunityInfo(communityId)` |
+| Get Community Members | `GET /twitter/community/members` | ✅ Supported | `client.communities.getCommunityMembers(communityId, cursor?)` |
+| Get Community Moderators | `GET /twitter/community/moderators` | ✅ Supported | `client.communities.getCommunityModerators(communityId, cursor?)` |
+| Get Community Tweets | `GET /twitter/community/tweets` | ✅ Supported | `client.communities.getCommunityTweets(communityId, cursor?)` |
+| Search Tweets From All Community | `GET /twitter/community/search` | ✅ Supported | `client.communities.searchCommunityTweets(query, queryType?, cursor?)` |
+
+### ✅ Trend Endpoint
+
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| Get Trends | `GET /twitter/trends` | ✅ Supported | `client.trends.getTrends(woeid)` |
+
+### ✅ Spaces Endpoint
+
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| Get Space Detail | `GET /twitter/space/detail` | ✅ Supported | `client.spaces.getSpaceDetail(spaceId)` |
+
+### ✅ Tweet Endpoint
+
+| Endpoint | Method | Status | Notes |
+|----------|--------|--------|-------|
+| Get Tweets by IDs | `GET /twitter/tweet/by_ids` | ✅ Supported | `client.tweets.getTweetsByIds(tweetIds)` |
+| Get Tweet Replies | `GET /twitter/tweet/replies` | ✅ Supported | `client.tweets.getTweetReplies(tweetId, cursor?)` |
+| Get Tweet Quotations | `GET /twitter/tweet/quotations` | ✅ Supported | `client.tweets.getTweetQuotations(tweetId, cursor?)` |
+| Get Tweet Retweeters | `GET /twitter/tweet/retweeters` | ✅ Supported | `client.tweets.getTweetRetweeters(tweetId, cursor?)` |
+| Get Tweet Thread Context | `GET /twitter/tweet/thread_context` | ✅ Supported | `client.tweets.getTweetThreadContext(tweetId)` |
+| Get Article | `GET /twitter/article` | ✅ Supported | `client.tweets.getArticle(articleId)` |
+| Advanced Search | `GET /twitter/search` | ✅ Supported | `client.tweets.searchTweets(query, queryType?, cursor?)` |
+
+## Not Supported Endpoints
+
+The following endpoint categories are **not yet implemented**:
+
+### ❌ Post & Action Endpoint V2
+
+- `POST /oapi/login` - Log in
+- `POST /oapi/upload/media` - Upload media
+- `POST /oapi/tweet/create` - Create tweet v2
+- `GET /oapi/dm/history` - Get History Messages By UserID
+- `POST /oapi/dm/send` - Send DM V2
+- `POST /oapi/tweet/retweet` - Retweet Tweet
+- `POST /oapi/tweet/delete` - Delete Tweet
+- `POST /oapi/user/follow` - Follow User
+- `POST /oapi/user/unfollow` - Unfollow User
+- `POST /oapi/tweet/like` - Like Tweet
+- `POST /oapi/tweet/unlike` - Unlike Tweet
+- `POST /oapi/community/create` - Create Community V2
+- `POST /oapi/community/delete` - Delete Community V2
+- `POST /oapi/community/join` - Join Community v2
+- `POST /oapi/community/leave` - Leave Community V2
+
+### ❌ Webhook/Websocket Filter Rule
+
+- `POST /oapi/webhook/filter/add` - Add Webhook/Websocket Tweet Filter Rule
+- `GET /oapi/webhook/filter/all` - Get ALL test Webhook/Websocket Tweet Filter Rules
+- `POST /oapi/webhook/filter/update` - Update Webhook/Websocket Tweet Filter Rule
+- `DELETE /oapi/webhook/filter/delete` - Delete Webhook/Websocket Tweet Filter Rule
+
+### ❌ Stream Endpoint
+
+- `POST /oapi/stream/add` - Add a twitter user to monitor his tweets
+- `POST /oapi/stream/remove` - Remove a user from monitor list
+
+### ❌ Deprecated Endpoints
+
+The following endpoints are marked as deprecated in the API documentation and are not implemented:
+
+- Login Endpoint (deprecated)
+  - `POST /oapi/login/step1` - Login Step 1: by email or username
+  - `POST /oapi/login/step2` - Login Step 2: by 2fa code
+
+- Tweet Action Endpoint (deprecated)
+  - `POST /oapi/tweet/upload_image` - Upload Image
+  - `POST /oapi/tweet/post` - Post/reply/quote a tweet
+  - `POST /oapi/tweet/like` - Like a tweet
+  - `POST /oapi/tweet/retweet` - Retweet a tweet
+
+## Implementation Status Summary
+
+- **Fully Supported**: 26 endpoints (9 User endpoints + 2 List endpoints + 1 My endpoint + 5 Communities endpoints + 1 Trend endpoint + 1 Spaces endpoint + 7 Tweet endpoints)
+- **Not Implemented**: ~16+ endpoints across multiple categories
+
+## Contributing
+
+Contributions are welcome! If you'd like to add support for additional endpoints, please refer to the existing implementation patterns in the `src/resources/` directory.
+
+## API Documentation
+
+For detailed API documentation, visit: [https://docs.twitterapi.io](https://docs.twitterapi.io)
+

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import { type HttpClientOptions } from "./httpClient";
+import { UsersApi } from "./resources/users";
+import { MyEndpointApi } from "./resources/myEndpoint";
+import { ListApi } from "./resources/list";
+import { CommunitiesApi } from "./resources/communities";
+import { TrendsApi } from "./resources/trends";
+import { SpacesApi } from "./resources/spaces";
+import { TweetsApi } from "./resources/tweets";
+export interface TwitterAPIIOClientOptions extends HttpClientOptions {
+}
+export declare class TwitterAPIIOClient {
+    readonly users: UsersApi;
+    readonly myEndpoint: MyEndpointApi;
+    readonly list: ListApi;
+    readonly communities: CommunitiesApi;
+    readonly trends: TrendsApi;
+    readonly spaces: SpacesApi;
+    readonly tweets: TweetsApi;
+    constructor(options: TwitterAPIIOClientOptions);
+}

package/dist/client.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwitterAPIIOClient = void 0;
+const httpClient_1 = require("./httpClient");
+const users_1 = require("./resources/users");
+const myEndpoint_1 = require("./resources/myEndpoint");
+const list_1 = require("./resources/list");
+const communities_1 = require("./resources/communities");
+const trends_1 = require("./resources/trends");
+const spaces_1 = require("./resources/spaces");
+const tweets_1 = require("./resources/tweets");
+class TwitterAPIIOClient {
+    users;
+    myEndpoint;
+    list;
+    communities;
+    trends;
+    spaces;
+    tweets;
+    constructor(options) {
+        const http = new httpClient_1.HttpClient(options);
+        this.users = new users_1.UsersApi(http);
+        this.myEndpoint = new myEndpoint_1.MyEndpointApi(http);
+        this.list = new list_1.ListApi(http);
+        this.communities = new communities_1.CommunitiesApi(http);
+        this.trends = new trends_1.TrendsApi(http);
+        this.spaces = new spaces_1.SpacesApi(http);
+        this.tweets = new tweets_1.TweetsApi(http);
+    }
+}
+exports.TwitterAPIIOClient = TwitterAPIIOClient;

package/dist/httpClient.d.ts

@@ -0,0 +1,10 @@
+export interface HttpClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export declare class HttpClient {
+    private apiKey;
+    private baseUrl;
+    constructor({ apiKey, baseUrl }: HttpClientOptions);
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+}

package/dist/httpClient.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+class HttpClient {
+    apiKey;
+    baseUrl;
+    constructor({ apiKey, baseUrl = "https://api.twitterapi.io" }) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(path, init = {}) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                ...(init.headers ?? {}),
+                "X-API-Key": this.apiKey,
+            },
+        });
+        if (!response.ok) {
+            throw new Error(response.statusText);
+        }
+        const json = await response.json();
+        return json;
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client";
+export * from "./types";

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// main client
+__exportStar(require("./client"), exports);
+// types
+__exportStar(require("./types"), exports);

package/dist/resources/communities.d.ts

@@ -0,0 +1,11 @@
+import type { HttpClient } from "../httpClient";
+import type { CommunityInfoResponse, CommunityMembersResponse, CommunityModeratorsResponse, CommunityTweetsResponse, CommunitySearchResponse } from "../types/communities";
+export declare class CommunitiesApi {
+    private http;
+    constructor(http: HttpClient);
+    getCommunityInfo(communityId: string): Promise<CommunityInfoResponse>;
+    getCommunityMembers(communityId: string, cursor?: string): Promise<CommunityMembersResponse>;
+    getCommunityModerators(communityId: string, cursor?: string): Promise<CommunityModeratorsResponse>;
+    getCommunityTweets(communityId: string, cursor?: string): Promise<CommunityTweetsResponse>;
+    searchCommunityTweets(query: string, queryType?: "latest" | "top", cursor?: string): Promise<CommunitySearchResponse>;
+}

package/dist/resources/communities.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunitiesApi = void 0;
+class CommunitiesApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async getCommunityInfo(communityId) {
+        const params = new URLSearchParams({ community_id: communityId });
+        const response = await this.http.request(`/twitter/community/info?${params.toString()}`);
+        return response;
+    }
+    async getCommunityMembers(communityId, cursor) {
+        const params = new URLSearchParams({ community_id: communityId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/community/members?${params.toString()}`);
+        return response;
+    }
+    async getCommunityModerators(communityId, cursor) {
+        const params = new URLSearchParams({ community_id: communityId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/community/moderators?${params.toString()}`);
+        return response;
+    }
+    async getCommunityTweets(communityId, cursor) {
+        const params = new URLSearchParams({ community_id: communityId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/community/tweets?${params.toString()}`);
+        return response;
+    }
+    async searchCommunityTweets(query, queryType, cursor) {
+        const params = new URLSearchParams({ query, queryType: queryType ?? "latest", cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/community/search?${params.toString()}`);
+        return response;
+    }
+}
+exports.CommunitiesApi = CommunitiesApi;

package/dist/resources/list.d.ts

@@ -0,0 +1,8 @@
+import type { HttpClient } from "../httpClient";
+import type { ListFollowersResponse, ListMembersResponse } from "../types/list";
+export declare class ListApi {
+    private http;
+    constructor(http: HttpClient);
+    getListFollowers(listId: string, cursor?: string): Promise<ListFollowersResponse>;
+    getListMembers(listId: string, cursor?: string): Promise<ListMembersResponse>;
+}

package/dist/resources/list.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListApi = void 0;
+class ListApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async getListFollowers(listId, cursor) {
+        const params = new URLSearchParams({ list_id: listId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/list/followers?${params.toString()}`);
+        return response;
+    }
+    async getListMembers(listId, cursor) {
+        const params = new URLSearchParams({ list_id: listId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/list/members?${params.toString()}`);
+        return response;
+    }
+}
+exports.ListApi = ListApi;

package/dist/resources/myEndpoint.d.ts

@@ -0,0 +1,7 @@
+import type { HttpClient } from "../httpClient";
+import type { MyAccountInfoResponse } from "../types/myEndpoint";
+export declare class MyEndpointApi {
+    private http;
+    constructor(http: HttpClient);
+    getMyAccountInfo(): Promise<MyAccountInfoResponse>;
+}

package/dist/resources/myEndpoint.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MyEndpointApi = void 0;
+class MyEndpointApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    getMyAccountInfo() {
+        return this.http.request("/oapi/my/info");
+    }
+}
+exports.MyEndpointApi = MyEndpointApi;

package/dist/resources/spaces.d.ts

@@ -0,0 +1,7 @@
+import type { HttpClient } from "../httpClient";
+import type { SpaceDetailResponse } from "../types/spaces";
+export declare class SpacesApi {
+    private http;
+    constructor(http: HttpClient);
+    getSpaceDetail(spaceId: string): Promise<SpaceDetailResponse>;
+}

package/dist/resources/spaces.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpacesApi = void 0;
+class SpacesApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async getSpaceDetail(spaceId) {
+        const params = new URLSearchParams({ space_id: spaceId });
+        const response = await this.http.request(`/twitter/space/detail?${params.toString()}`);
+        return response;
+    }
+}
+exports.SpacesApi = SpacesApi;

package/dist/resources/trends.d.ts

@@ -0,0 +1,7 @@
+import type { HttpClient } from "../httpClient";
+import type { TrendsResponse } from "../types/trends";
+export declare class TrendsApi {
+    private http;
+    constructor(http: HttpClient);
+    getTrends(woeid: number): Promise<TrendsResponse>;
+}

package/dist/resources/trends.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrendsApi = void 0;
+class TrendsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async getTrends(woeid) {
+        const params = new URLSearchParams({ woeid: woeid.toString() });
+        const response = await this.http.request(`/twitter/trends?${params.toString()}`);
+        return response;
+    }
+}
+exports.TrendsApi = TrendsApi;

package/dist/resources/tweets.d.ts

@@ -0,0 +1,13 @@
+import type { HttpClient } from "../httpClient";
+import type { TweetsByIdsResponse, TweetRepliesResponse, TweetQuotationsResponse, TweetRetweetersResponse, TweetThreadContextResponse, ArticleResponse, SearchTweetsResponse } from "../types/tweets";
+export declare class TweetsApi {
+    private http;
+    constructor(http: HttpClient);
+    getTweetsByIds(tweetIds: string[]): Promise<TweetsByIdsResponse>;
+    getTweetReplies(tweetId: string, cursor?: string): Promise<TweetRepliesResponse>;
+    getTweetQuotations(tweetId: string, cursor?: string): Promise<TweetQuotationsResponse>;
+    getTweetRetweeters(tweetId: string, cursor?: string): Promise<TweetRetweetersResponse>;
+    getTweetThreadContext(tweetId: string): Promise<TweetThreadContextResponse>;
+    getArticle(articleId: string): Promise<ArticleResponse>;
+    searchTweets(query: string, queryType?: "latest" | "top", cursor?: string): Promise<SearchTweetsResponse>;
+}

package/dist/resources/tweets.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TweetsApi = void 0;
+class TweetsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async getTweetsByIds(tweetIds) {
+        const params = new URLSearchParams({ tweet_ids: tweetIds.join(",") });
+        const response = await this.http.request(`/twitter/tweet/by_ids?${params.toString()}`);
+        return response;
+    }
+    async getTweetReplies(tweetId, cursor) {
+        const params = new URLSearchParams({ tweet_id: tweetId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/tweet/replies?${params.toString()}`);
+        return response;
+    }
+    async getTweetQuotations(tweetId, cursor) {
+        const params = new URLSearchParams({ tweet_id: tweetId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/tweet/quotations?${params.toString()}`);
+        return response;
+    }
+    async getTweetRetweeters(tweetId, cursor) {
+        const params = new URLSearchParams({ tweet_id: tweetId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/tweet/retweeters?${params.toString()}`);
+        return response;
+    }
+    async getTweetThreadContext(tweetId) {
+        const params = new URLSearchParams({ tweet_id: tweetId });
+        const response = await this.http.request(`/twitter/tweet/thread_context?${params.toString()}`);
+        return response;
+    }
+    async getArticle(articleId) {
+        const params = new URLSearchParams({ article_id: articleId });
+        const response = await this.http.request(`/twitter/article?${params.toString()}`);
+        return response;
+    }
+    async searchTweets(query, queryType, cursor) {
+        const params = new URLSearchParams({ query, queryType: queryType ?? "latest", cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/search?${params.toString()}`);
+        return response;
+    }
+}
+exports.TweetsApi = TweetsApi;

package/dist/resources/users.d.ts

@@ -0,0 +1,15 @@
+import type { HttpClient } from "../httpClient";
+import type { FollowRelationshipResponse, SearchUserByKeywordResponse, UserFollowersResponse, UserFollowingsResponse, UserInfoResponse, UserLatestTweetsResponse, UserMentionsResponse, UserProfileAboutResponse, UserVerifiedFollowersResponse } from "../types/users";
+export declare class UsersApi {
+    private http;
+    constructor(http: HttpClient);
+    getUserProfileAbout(userName: string): Promise<UserProfileAboutResponse>;
+    getUserInfo(userName: string): Promise<UserInfoResponse>;
+    getUserLatestTweets(userId?: string, userName?: string, cursor?: string, pageSize?: number, includeReplies?: boolean): Promise<UserLatestTweetsResponse>;
+    getUserFollowers(userName: string, cursor?: string, pageSize?: number): Promise<UserFollowersResponse>;
+    getUserFollowings(userName: string, cursor?: string, pageSize?: number): Promise<UserFollowingsResponse>;
+    getUserMentions(userName: string, sinceTime: number, untilTime: number, cursor?: string): Promise<UserMentionsResponse>;
+    checkFollowRelationship(sourceUserName: string, targetUserName: string): Promise<FollowRelationshipResponse>;
+    searchUserByKeyword(query: string, cursor?: string): Promise<SearchUserByKeywordResponse>;
+    getUserVerifiedFollowers(userId: string, cursor?: string): Promise<UserVerifiedFollowersResponse>;
+}

package/dist/resources/users.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersApi = void 0;
+class UsersApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async getUserProfileAbout(userName) {
+        const params = new URLSearchParams({ userName });
+        const response = await this.http.request(`/twitter/user_about?${params.toString()}`);
+        return response;
+    }
+    async getUserInfo(userName) {
+        const params = new URLSearchParams({ userName });
+        const response = await this.http.request(`/twitter/user/info?${params.toString()}`);
+        return response.data;
+    }
+    async getUserLatestTweets(userId, userName, cursor, pageSize, includeReplies) {
+        if (!userId && !userName) {
+            throw new Error("Either userId or userName is required");
+        }
+        const params = new URLSearchParams();
+        if (userId)
+            params.append("userId", userId);
+        if (userName)
+            params.append("userName", userName);
+        if (cursor && cursor.trim() !== "")
+            params.append("cursor", cursor);
+        params.append("pageSize", pageSize?.toString() ?? "200");
+        params.append("includeReplies", includeReplies?.toString() ?? "false");
+        const url = `/twitter/user/latest_tweets?${params.toString()}`;
+        const response = await this.http.request(url);
+        // Check if tweets are at the top level (direct response)
+        if ('tweets' in response && Array.isArray(response.tweets)) {
+            return response;
+        }
+        // Handle response wrapped in { status, msg, data }
+        if ('data' in response && response.data) {
+            const data = response.data;
+            // Check if data contains tweets array (expected structure per docs)
+            if ('tweets' in data && Array.isArray(data.tweets)) {
+                return {
+                    tweets: data.tweets,
+                    has_next_page: data.has_next_page ?? false,
+                    next_cursor: data.next_cursor ?? "",
+                    status: data.status || response.status || "success",
+                    message: data.message || response.msg
+                };
+            }
+            // If data doesn't have tweets, return empty structure (API might be returning wrong data)
+            return {
+                tweets: [],
+                has_next_page: false,
+                next_cursor: "",
+                status: response.status || "success",
+                message: response.msg
+            };
+        }
+        return response;
+    }
+    async getUserFollowers(userName, cursor, pageSize) {
+        const params = new URLSearchParams({ userName, cursor: cursor ?? "", pageSize: pageSize?.toString() ?? "200" });
+        const response = await this.http.request(`/twitter/user/followers?${params.toString()}`);
+        return response;
+    }
+    async getUserFollowings(userName, cursor, pageSize) {
+        const params = new URLSearchParams({ userName, cursor: cursor ?? "", pageSize: pageSize?.toString() ?? "200" });
+        const response = await this.http.request(`/twitter/user/followings?${params.toString()}`);
+        return response;
+    }
+    async getUserMentions(userName, sinceTime, untilTime, cursor) {
+        const params = new URLSearchParams({
+            userName,
+            sinceTime: sinceTime.toString(),
+            untilTime: untilTime.toString()
+        });
+        if (cursor && cursor.trim() !== "") {
+            params.append("cursor", cursor);
+        }
+        const url = `/twitter/user/mentions?${params.toString()}`;
+        const response = await this.http.request(url);
+        // Check if tweets are at the top level (direct response)
+        if ('tweets' in response && Array.isArray(response.tweets)) {
+            return response;
+        }
+        // Handle response wrapped in { status, msg, data }
+        if ('data' in response && response.data) {
+            const data = response.data;
+            // Check if data contains tweets array (expected structure per docs)
+            if ('tweets' in data && Array.isArray(data.tweets)) {
+                return {
+                    tweets: data.tweets,
+                    has_next_page: data.has_next_page ?? false,
+                    next_cursor: data.next_cursor ?? "",
+                    status: data.status || response.status || "success",
+                    message: data.message || response.msg
+                };
+            }
+            // If data doesn't have tweets, return empty structure
+            return {
+                tweets: [],
+                has_next_page: false,
+                next_cursor: "",
+                status: response.status || "success",
+                message: response.msg
+            };
+        }
+        return response;
+    }
+    async checkFollowRelationship(sourceUserName, targetUserName) {
+        const params = new URLSearchParams({ source_user_name: sourceUserName, target_user_name: targetUserName });
+        const response = await this.http.request(`/twitter/user/check_follow_relationship?${params.toString()}`);
+        return response;
+    }
+    async searchUserByKeyword(query, cursor) {
+        const params = new URLSearchParams({ query, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/user/search?${params.toString()}`);
+        return response;
+    }
+    async getUserVerifiedFollowers(userId, cursor) {
+        const params = new URLSearchParams({ user_id: userId, cursor: cursor ?? "" });
+        const response = await this.http.request(`/twitter/user/verifiedFollowers?${params.toString()}`);
+        return response;
+    }
+}
+exports.UsersApi = UsersApi;

package/dist/types/communities.d.ts

@@ -0,0 +1,43 @@
+import type { UserInfoResponse } from "./users";
+import type { Tweet } from "./tweets";
+export interface CommunityInfoResponse {
+    id: string;
+    name: string;
+    description: string;
+    member_count: number;
+    moderator_count: number;
+    created_at: string;
+    rules?: string[];
+    banner_image?: string;
+    profile_image?: string;
+    status: string;
+    message?: string;
+}
+export interface CommunityMembersResponse {
+    members: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    msg?: string;
+}
+export interface CommunityModeratorsResponse {
+    moderators: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    msg?: string;
+}
+export interface CommunityTweetsResponse {
+    tweets: Tweet[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface CommunitySearchResponse {
+    tweets: Tweet[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}

package/dist/types/communities.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./users";
+export * from "./tweets";
+export * from "./communities";
+export * from "./spaces";
+export * from "./trends";
+export * from "./list";
+export * from "./myEndpoint";

package/dist/types/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./users"), exports);
+__exportStar(require("./tweets"), exports);
+__exportStar(require("./communities"), exports);
+__exportStar(require("./spaces"), exports);
+__exportStar(require("./trends"), exports);
+__exportStar(require("./list"), exports);
+__exportStar(require("./myEndpoint"), exports);

package/dist/types/list.d.ts

@@ -0,0 +1,15 @@
+import type { UserInfoResponse } from "./users";
+export interface ListFollowersResponse {
+    followers: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    msg?: string;
+}
+export interface ListMembersResponse {
+    members: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    msg?: string;
+}

package/dist/types/list.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/myEndpoint.d.ts

@@ -0,0 +1,4 @@
+export interface MyAccountInfoResponse {
+    recharge_credits: number;
+    total_bonus_credits: number;
+}

package/dist/types/myEndpoint.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/spaces.d.ts

@@ -0,0 +1,23 @@
+import type { UserInfoResponse } from "./users";
+export interface SpaceDetailResponse {
+    id: string;
+    state: string;
+    title?: string;
+    created_at?: string;
+    started_at?: string;
+    ended_at?: string;
+    updated_at?: string;
+    host_ids?: string[];
+    speaker_ids?: string[];
+    creator_id?: string;
+    lang?: string;
+    is_ticketed?: boolean;
+    participant_count?: number;
+    subscriber_count?: number;
+    scheduled_start?: string;
+    creator?: UserInfoResponse;
+    hosts?: UserInfoResponse[];
+    speakers?: UserInfoResponse[];
+    status: string;
+    message?: string;
+}

package/dist/types/spaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/trends.d.ts

@@ -0,0 +1,19 @@
+export interface Trend {
+    name: string;
+    url: string;
+    promoted_content?: unknown;
+    query: string;
+    tweet_volume?: number;
+}
+export interface TrendLocation {
+    name: string;
+    woeid: number;
+}
+export interface TrendsResponse {
+    trends: Trend[];
+    as_of: string;
+    created_at: string;
+    locations: TrendLocation[];
+    status: string;
+    message?: string;
+}

package/dist/types/trends.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/tweets.d.ts

@@ -0,0 +1,94 @@
+import type { UserInfoResponse } from "./users";
+export interface Tweet {
+    type: string;
+    id: string;
+    url: string;
+    text: string;
+    source: string;
+    retweetCount: number;
+    replyCount: number;
+    likeCount: number;
+    quoteCount: number;
+    viewCount: number;
+    createdAt: string;
+    lang: string;
+    bookmarkCount: number;
+    isReply: boolean;
+    inReplyToId?: string;
+    conversationId: string;
+    displayTextRange?: number[];
+    inReplyToUserId?: string;
+    inReplyToUsername?: string;
+    author: UserInfoResponse;
+    entities: {
+        hashtags: {
+            indices: number[];
+            text: string;
+        }[];
+        urls: {
+            display_url: string;
+            expanded_url: string;
+            indices: number[];
+            url: string;
+        }[];
+        user_mentions: {
+            id_str: string;
+            name: string;
+            screen_name: string;
+        }[];
+    };
+    quoted_tweet?: unknown;
+    retweeted_tweet?: unknown;
+    isLimitedReply?: boolean;
+}
+export interface TweetsByIdsResponse {
+    tweets: Tweet[];
+    status: string;
+    message?: string;
+}
+export interface TweetRepliesResponse {
+    tweets: Tweet[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface TweetQuotationsResponse {
+    tweets: Tweet[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface TweetRetweetersResponse {
+    retweeters: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface TweetThreadContextResponse {
+    tweets: Tweet[];
+    status: string;
+    message?: string;
+}
+export interface ArticleResponse {
+    article: {
+        id: string;
+        title: string;
+        description?: string;
+        url: string;
+        author?: UserInfoResponse;
+        published_at?: string;
+        content?: string;
+    };
+    status: string;
+    message?: string;
+}
+export interface SearchTweetsResponse {
+    tweets: Tweet[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}

package/dist/types/tweets.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/users.d.ts

@@ -0,0 +1,149 @@
+import type { Tweet } from "./tweets";
+export interface UserInfoResponse {
+    type: string;
+    userName: string;
+    url: string;
+    id: string;
+    name: string;
+    isBlueVerified: boolean;
+    verifiedType: string;
+    profilePicture: string;
+    coverPicture: string;
+    description: string;
+    location: string;
+    followers: number;
+    following: number;
+    canDm: boolean;
+    createdAt: string;
+    favouritesCount: number;
+    hasCustomTimelines: boolean;
+    isTranslator: boolean;
+    mediaCount: number;
+    statusesCount: number;
+    withheldInCountries: string[];
+    affiliatesHighlightedLabel: unknown;
+    possiblySensitive: boolean;
+    pinnedTweetIds: string[];
+    isAutomated: boolean;
+    automatedBy: string;
+    unavailable?: boolean;
+    message?: string;
+    unavailableReason?: string;
+    profile_bio: {
+        description: string;
+        entities: {
+            description: {
+                urls: {
+                    url: string;
+                    expanded_url: string;
+                    display_url: string;
+                    indices: number[];
+                }[];
+            };
+            url: {
+                urls: {
+                    url: string;
+                    expanded_url: string;
+                    display_url: string;
+                    indices: number[];
+                }[];
+            };
+        };
+    };
+}
+export interface UserFollowersResponse {
+    followers: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface UserFollowingsResponse {
+    followings: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface UserProfileAboutResponse {
+    data: {
+        id: string;
+        name: string;
+        userName: string;
+        createdAt: string;
+        isBlueVerified: boolean;
+        protected: boolean;
+        affiliates_highlighted_label?: {
+            label: {
+                badge?: {
+                    url: string;
+                };
+                description: string;
+                url?: {
+                    url: string;
+                    urlType: string;
+                };
+                userLabelDisplayType: string;
+                userLabelType: string;
+            };
+        };
+        about_profile?: {
+            account_based_in?: string;
+            location_accurate?: boolean;
+            learn_more_url?: string;
+            affiliate_username?: string;
+            source?: string;
+            username_changes?: {
+                count: string;
+            };
+        };
+        identity_profile_labels_highlighted_label?: {
+            label: {
+                description: string;
+                badge?: {
+                    url: string;
+                };
+                url?: {
+                    url: string;
+                    urlType: string;
+                };
+                userLabelDisplayType: string;
+                userLabelType: string;
+            };
+        };
+    };
+}
+export interface UserLatestTweetsResponse {
+    tweets: Tweet[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface UserMentionsResponse {
+    tweets: Tweet[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    message?: string;
+}
+export interface FollowRelationshipResponse {
+    data: {
+        following: boolean;
+        followed_by: boolean;
+    };
+    status: string;
+    message?: string;
+}
+export interface SearchUserByKeywordResponse {
+    users: UserInfoResponse[];
+    has_next_page: boolean;
+    next_cursor: string;
+    status: string;
+    msg?: string;
+}
+export interface UserVerifiedFollowersResponse {
+    followers: UserInfoResponse[];
+    status: string;
+    message?: string;
+}

package/dist/types/users.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "twitterapi-io-client",
+  "version": "1.0.0",
+  "description": "A TypeScript client library for the TwitterAPI.io API",
+  "author": "jorvixsky",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "typescript": "5.9.3",
+    "vitest": "4.0.15"
+  }
+}