@cm-growth-hacking/twitter-client 0.2.0

package/dist/client/TwitterClient.js

@@ -0,0 +1,472 @@
+import { GraphQLClient } from './graphql.js';
+import { RestClient } from './rest.js';
+import { queryIdManager } from './query-ids.js';
+export class TwitterClient {
+    graphql;
+    rest;
+    constructor(options) {
+        this.graphql = new GraphQLClient({
+            authToken: options.authToken,
+            ct0: options.ct0,
+            timeout: options.timeout,
+        });
+        this.rest = new RestClient(options.authToken, options.ct0, 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36', options.timeout);
+    }
+    /**
+     * Verify authentication and get current user info
+     */
+    async whoami() {
+        const result = await this.graphql.getCurrentUser();
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                code: result.code,
+            };
+        }
+        // Parse user data from GraphQL response
+        // The response structure is: result.data (which is AboutAccountResponse)
+        const userData = result.data;
+        if (!userData) {
+            return {
+                success: false,
+                error: 'Could not extract user data from GraphQL response',
+                code: 'NETWORK_ERROR',
+            };
+        }
+        // Use existing parseUser function
+        const { parseUser } = await import('./parsers.js');
+        const user = parseUser(userData);
+        if (!user) {
+            return {
+                success: false,
+                error: 'Could not parse user data',
+                code: 'NETWORK_ERROR',
+            };
+        }
+        return {
+            success: true,
+            user,
+        };
+    }
+    /**
+     * Search for tweets
+     */
+    async search(query, count = 20, product = 'Top') {
+        if (count < 1 || count > 200) {
+            return {
+                success: false,
+                error: 'count must be between 1 and 200',
+                code: 'INVALID_INPUT',
+            };
+        }
+        // Build features for search (enables view counts and other fields)
+        const features = {
+            rweb_video_screen_enabled: true,
+            profile_label_improvements_pcf_label_in_post_enabled: true,
+            responsive_web_profile_redirect_enabled: true,
+            rweb_tipjar_consumption_enabled: true,
+            verified_phone_label_enabled: false,
+            creator_subscriptions_tweet_preview_api_enabled: true,
+            responsive_web_graphql_timeline_navigation_enabled: true,
+            responsive_web_graphql_exclude_directive_enabled: true,
+            responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+            premium_content_api_read_enabled: false,
+            communities_web_enable_tweet_community_results_fetch: true,
+            c9s_tweet_anatomy_moderator_badge_enabled: true,
+            responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+            responsive_web_grok_analyze_post_followups_enabled: false,
+            responsive_web_grok_annotations_enabled: false,
+            responsive_web_jetfuel_frame: true,
+            post_ctas_fetch_enabled: true,
+            responsive_web_grok_share_attachment_enabled: true,
+            responsive_web_edit_tweet_api_enabled: true,
+            graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+            view_counts_everywhere_api_enabled: true,
+            longform_notetweets_consumption_enabled: true,
+            responsive_web_twitter_article_tweet_consumption_enabled: true,
+            tweet_awards_web_tipping_enabled: false,
+            responsive_web_grok_show_grok_translated_post: false,
+            responsive_web_grok_analysis_button_from_backend: true,
+            creator_subscriptions_quote_tweet_preview_enabled: false,
+            freedom_of_speech_not_reach_fetch_enabled: true,
+            standardized_nudges_misinfo: true,
+            tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+            rweb_video_timestamps_enabled: true,
+            longform_notetweets_rich_text_read_enabled: true,
+            longform_notetweets_inline_media_enabled: true,
+            responsive_web_grok_image_annotation_enabled: true,
+            responsive_web_grok_imagine_annotation_enabled: true,
+            responsive_web_grok_community_note_auto_translation_is_enabled: false,
+            articles_preview_enabled: true,
+            responsive_web_enhance_cards_enabled: false,
+        };
+        const result = await this.graphql.request('SearchTimeline', {
+            rawQuery: query,
+            count: Math.min(count, 20),
+            querySource: 'typed_query',
+            product: product,
+        }, features);
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                code: result.code,
+            };
+        }
+        const { parseTweet, extractTweetsFromInstructions } = await import('./parsers.js');
+        const instructions = result.data.search_by_raw_query?.search_timeline?.timeline?.instructions || [];
+        const tweets = extractTweetsFromInstructions(instructions);
+        return {
+            success: true,
+            tweets: tweets.slice(0, count),
+        };
+    }
+    /**
+     * Get a single tweet by ID or URL
+     */
+    async getTweet(tweetIdOrUrl) {
+        // Extract tweet ID from URL if needed
+        let tweetId = tweetIdOrUrl;
+        const urlMatch = tweetIdOrUrl.match(/status\/(\d+)/);
+        if (urlMatch) {
+            tweetId = urlMatch[1];
+        }
+        const result = await this.graphql.request('TweetDetail', {
+            focalTweetId: tweetId,
+            with_rux_injections: false,
+            includePromotedContent: false,
+            withCommunity: true,
+            withQuickPromoteEligibilityTweetFields: true,
+            withBirdwatchNotes: true,
+            withVoice: true,
+            withV2Timeline: true,
+        });
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                code: result.code,
+            };
+        }
+        const { parseTweet } = await import('./parsers.js');
+        const tweetData = result.data.tweet_results?.result;
+        const tweet = parseTweet(tweetData);
+        if (!tweet) {
+            return {
+                success: false,
+                error: 'Could not parse tweet',
+                code: 'NETWORK_ERROR',
+            };
+        }
+        return {
+            success: true,
+            tweet,
+        };
+    }
+    /**
+     * Get thread (conversation) for a tweet
+     */
+    async getThread(tweetIdOrUrl) {
+        const tweetResult = await this.getTweet(tweetIdOrUrl);
+        if (!tweetResult.success) {
+            return tweetResult;
+        }
+        // For now, just return the single tweet
+        // Thread expansion can be added later with cursor-based pagination
+        return {
+            success: true,
+            tweets: [tweetResult.tweet],
+        };
+    }
+    /**
+     * Get tweets from a user's timeline
+     */
+    async getUserTweets(username, count = 20, cursor) {
+        if (count < 1 || count > 200) {
+            return {
+                success: false,
+                error: 'count must be between 1 and 200',
+                code: 'INVALID_INPUT',
+            };
+        }
+        // First, get user ID using UserByScreenName (GET request)
+        const queryId = queryIdManager.getQueryId('UserByScreenName');
+        const ids = Array.isArray(queryId) ? queryId : [queryId];
+        let userId;
+        // Try each query ID
+        for (const id of ids) {
+            try {
+                const variables = {
+                    screen_name: username,
+                    withSafetyModeUserFields: true,
+                };
+                const features = {
+                    hidden_profile_subscriptions_enabled: true,
+                    hidden_profile_likes_enabled: true,
+                    responsive_web_graphql_exclude_directive_enabled: true,
+                    verified_phone_label_enabled: false,
+                };
+                const fieldToggles = {
+                    withAuxiliaryUserLabels: false,
+                };
+                const params = new URLSearchParams({
+                    variables: JSON.stringify(variables),
+                    features: JSON.stringify(features),
+                    fieldToggles: JSON.stringify(fieldToggles),
+                });
+                const url = `https://x.com/i/api/graphql/${id}/UserByScreenName?${params.toString()}`;
+                const response = await this.graphql.fetchWithTimeout(url, {
+                    method: 'GET',
+                    headers: this.graphql.getHeaders(),
+                });
+                if (!response.ok) {
+                    if (response.status === 404) {
+                        continue; // Try next query ID
+                    }
+                    return {
+                        success: false,
+                        error: `HTTP ${response.status}: User lookup failed`,
+                        code: 'NETWORK_ERROR',
+                    };
+                }
+                const data = await response.json();
+                if (data.data?.user?.result?.__typename === 'UserUnavailable') {
+                    return {
+                        success: false,
+                        error: `User @${username} not found`,
+                        code: 'NETWORK_ERROR',
+                    };
+                }
+                userId = data.data?.user?.result?.rest_id;
+                if (userId)
+                    break;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!userId) {
+            return {
+                success: false,
+                error: 'Failed to resolve user ID',
+                code: 'NETWORK_ERROR',
+            };
+        }
+        // Now fetch tweets using UserTweets
+        const tweetsResult = await this.graphql.request('UserTweets', {
+            userId,
+            count: Math.min(count, 40),
+            cursor,
+            includePromotedContent: false,
+            withClientEventToken: false,
+            withBirdwatchNotes: false,
+            withVoice: true,
+            withV2Timeline: true,
+        });
+        if (!tweetsResult.success) {
+            return {
+                success: false,
+                error: tweetsResult.error,
+                code: tweetsResult.code,
+            };
+        }
+        const { extractTweetsFromInstructions } = await import('./parsers.js');
+        const instructions = tweetsResult.data.user?.result?.timeline_response?.timeline?.instructions || [];
+        const tweets = extractTweetsFromInstructions(instructions);
+        return {
+            success: true,
+            tweets: tweets.slice(0, count),
+        };
+    }
+    /**
+     * Post a new tweet
+     */
+    async tweet(text) {
+        if (!text || text.trim().length === 0) {
+            return {
+                success: false,
+                error: 'Tweet text cannot be empty',
+                code: 'INVALID_INPUT',
+            };
+        }
+        if (text.length > 280) {
+            return {
+                success: false,
+                error: 'Tweet text cannot exceed 280 characters',
+                code: 'INVALID_INPUT',
+            };
+        }
+        const result = await this.graphql.request('CreateTweet', {
+            tweet_text: text,
+            dark_request: false,
+            media: {
+                media_entities: [],
+                possibly_sensitive: false,
+            },
+            semantic_annotation_ids: [],
+        }, {
+            rweb_video_screen_enabled: true,
+            responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+            responsive_web_grok_analyze_post_followups_enabled: false,
+            responsive_web_grok_annotations_enabled: false,
+            responsive_web_grok_show_grok_translated_post: false,
+            responsive_web_jetfuel_frame: true,
+            longform_notetweets_consumption_enabled: true,
+            responsive_web_twitter_article_tweet_consumption_enabled: true,
+            tweet_awards_web_tipping_enabled: false,
+            responsive_graphql_exclude_directive_enabled: true,
+            responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+            responsive_web_graphql_timeline_navigation_enabled: true,
+            c9s_tweet_anatomy_moderator_badge_enabled: true,
+            verified_phone_label_enabled: false,
+            responsive_web_media_download_video_enabled: false,
+        });
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                code: result.code,
+            };
+        }
+        const tweetId = result.data.create_tweet?.tweet_results?.result?.rest_id;
+        if (!tweetId) {
+            return {
+                success: false,
+                error: 'Could not parse tweet ID from response',
+                code: 'NETWORK_ERROR',
+            };
+        }
+        return {
+            success: true,
+            tweetId,
+        };
+    }
+    /**
+     * Reply to a tweet
+     */
+    async reply(tweetId, text) {
+        if (!text || text.trim().length === 0) {
+            return {
+                success: false,
+                error: 'Reply text cannot be empty',
+                code: 'INVALID_INPUT',
+            };
+        }
+        if (text.length > 280) {
+            return {
+                success: false,
+                error: 'Reply text cannot exceed 280 characters',
+                code: 'INVALID_INPUT',
+            };
+        }
+        const result = await this.graphql.request('CreateTweet', {
+            tweet_text: text,
+            media: {
+                media_entities: [],
+                tagged_users: [],
+            },
+            semantic_annotation_ids: [],
+            reply_settings: {
+                in_reply_to_tweet_id: tweetId,
+            },
+        });
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                code: result.code,
+            };
+        }
+        const newTweetId = result.data.create_tweet?.tweet_results?.result?.rest_id;
+        if (!newTweetId) {
+            return {
+                success: false,
+                error: 'Could not parse tweet ID from response',
+                code: 'NETWORK_ERROR',
+            };
+        }
+        return {
+            success: true,
+            tweetId: newTweetId,
+        };
+    }
+    /**
+     * Get news/for you timeline
+     */
+    async getNews(count = 20) {
+        if (count < 1 || count > 200) {
+            return {
+                success: false,
+                error: 'count must be between 1 and 200',
+                code: 'INVALID_INPUT',
+            };
+        }
+        const result = await this.graphql.request('NewsForYou', {
+            count: Math.min(count, 40),
+            includePromotedContent: false,
+            latestControlAvailable: true,
+            requestContext: 'launch',
+            withClientEventToken: false,
+            withBirdwatchNotes: false,
+            withVoice: true,
+            withV2Timeline: true,
+        });
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                code: result.code,
+            };
+        }
+        const { extractTweetsFromInstructions } = await import('./parsers.js');
+        const instructions = result.data.home?.home_timeline_urt?.instructions || [];
+        const tweets = extractTweetsFromInstructions(instructions);
+        // Transform tweets into news items
+        const items = tweets.slice(0, count).map((tweet) => ({
+            id: tweet.id,
+            headline: tweet.text,
+            tweets: [tweet],
+        }));
+        return {
+            success: true,
+            items,
+        };
+    }
+    /**
+     * Get mentions timeline
+     */
+    async getMentions(count = 20) {
+        if (count < 1 || count > 200) {
+            return {
+                success: false,
+                error: 'count must be between 1 and 200',
+                code: 'INVALID_INPUT',
+            };
+        }
+        const result = await this.graphql.request('MentionsTimeline', {
+            count: Math.min(count, 40),
+            includePromotedContent: false,
+            latestControlAvailable: true,
+            requestContext: 'launch',
+            withClientEventToken: false,
+            withBirdwatchNotes: false,
+            withVoice: true,
+            withV2Timeline: true,
+        });
+        if (!result.success) {
+            return {
+                success: false,
+                error: result.error,
+                code: result.code,
+            };
+        }
+        const { extractTweetsFromInstructions } = await import('./parsers.js');
+        const instructions = result.data.home?.home_timeline_urt?.instructions || [];
+        const tweets = extractTweetsFromInstructions(instructions);
+        return {
+            success: true,
+            tweets: tweets.slice(0, count),
+        };
+    }
+}

package/dist/client/auth.d.ts

@@ -0,0 +1,21 @@
+export interface TwitterCredentials {
+    authToken: string;
+    ct0: string;
+}
+export interface ResolvedCredentials {
+    authToken: string;
+    ct0: string;
+    source: string;
+}
+/**
+ * Resolve Twitter credentials from environment variables or config
+ */
+export declare function resolveCredentials(): ResolvedCredentials;
+/**
+ * Validate credentials format
+ */
+export declare function validateCredentials(creds: TwitterCredentials): {
+    valid: boolean;
+    error?: string;
+};
+//# sourceMappingURL=auth.d.ts.map

package/dist/client/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/client/auth.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,mBAAmB,CA2BxD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAcjG"}

package/dist/client/auth.js

@@ -0,0 +1,42 @@
+/**
+ * Resolve Twitter credentials from environment variables or config
+ */
+export function resolveCredentials() {
+    // Check environment variables first
+    const authToken = process.env.TWITTER_AUTH_TOKEN ||
+        process.env.AUTH_TOKEN ||
+        process.env.auth_token;
+    const ct0 = process.env.TWITTER_CT0 ||
+        process.env.CT0 ||
+        process.env.ct0;
+    if (!authToken || !ct0) {
+        throw new Error('Missing credentials. Set TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables.\n\n' +
+            'Get tokens from browser:\n' +
+            '1. Open https://x.com in browser\n' +
+            '2. DevTools → Application → Cookies\n' +
+            '3. Copy auth_token and ct0 values');
+    }
+    return {
+        authToken,
+        ct0,
+        source: 'environment',
+    };
+}
+/**
+ * Validate credentials format
+ */
+export function validateCredentials(creds) {
+    if (!creds.authToken || typeof creds.authToken !== 'string') {
+        return { valid: false, error: 'Invalid auth_token' };
+    }
+    if (!creds.ct0 || typeof creds.ct0 !== 'string') {
+        return { valid: false, error: 'Invalid ct0 token' };
+    }
+    if (creds.authToken.length < 10) {
+        return { valid: false, error: 'auth_token too short' };
+    }
+    if (creds.ct0.length < 10) {
+        return { valid: false, error: 'ct0 token too short' };
+    }
+    return { valid: true };
+}

package/dist/client/graphql.d.ts

@@ -0,0 +1,49 @@
+import type { Result } from './types.js';
+export interface GraphQLError {
+    code?: number;
+    message: string;
+}
+export interface GraphQLResponse<T> {
+    data?: T;
+    errors?: GraphQLError[];
+}
+export interface AboutAccountResponse {
+    rest_id?: string;
+    legacy?: {
+        screen_name?: string;
+        name?: string;
+        followers_count?: number;
+        friends_count?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare class GraphQLClient {
+    private authToken;
+    private ct0;
+    private userAgent;
+    private timeout;
+    private clientUuid;
+    private clientDeviceId;
+    constructor(options: {
+        authToken: string;
+        ct0: string;
+        timeout?: number;
+        userAgent?: string;
+    });
+    private createTransactionId;
+    getHeaders(): Record<string, string>;
+    fetchWithTimeout(url: string, init: RequestInit): Promise<Response>;
+    private getErrorCode;
+    private validateResponse;
+    request<T>(operation: string, variables: Record<string, unknown>, features?: Record<string, boolean | string | number>): Promise<Result<{
+        data: T;
+    }>>;
+    /**
+     * Fetch the authenticated user's information using GraphQL
+     */
+    getCurrentUser(): Promise<Result<{
+        data: AboutAccountResponse;
+    }>>;
+}
+//# sourceMappingURL=graphql.d.ts.map

package/dist/client/graphql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql.d.ts","sourceRoot":"","sources":["../../src/client/graphql.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAa,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,cAAc,CAAS;gBAEnB,OAAO,EAAE;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;IAWD,OAAO,CAAC,mBAAmB;IAIpB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAoB9B,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAehF,OAAO,CAAC,YAAY;YAgBN,gBAAgB;IA2BxB,OAAO,CAAC,CAAC,EACb,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAyF/B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;QAAE,IAAI,EAAE,oBAAoB,CAAA;KAAE,CAAC,CAAC;CAwBxE"}