Package com.tnsai.tools.social

Class TwitterTools

java.lang.Object

com.tnsai.tools.social.TwitterTools

public class TwitterTools
extends Object

Function-shape Twitter / X tools — read-only via the Twitter v2 REST API. Replaces the legacy TwitterTool (single dispatched tool).

Method	Endpoint	Idempotent
twitterSearch(java.lang.String, int)	GET /2/tweets/search/recent	true
twitterUser(java.lang.String)	GET /2/users/by/username/{username}	true
twitterTimeline(java.lang.String, int)	GET /2/users/{id}/tweets	true

Requires TWITTER_BEARER_TOKEN. Free tier is severely limited (1,500 tweet reads / month) — Basic tier ($100/mo) recommended for production.

Search supports the full v2 query syntax: from:user, -is:retweet, lang:en, #hashtag, etc.

Since:

0.5.7 (Phase 2 batch 16a — built-in tool migration to function shape, see #188)

Constructor Summary

Constructors

Constructor	Description
TwitterTools()	Default constructor — picks TWITTER_BEARER_TOKEN from env.
TwitterTools(String bearerToken)	Explicit-token constructor.
TwitterTools(String bearerToken, okhttp3.OkHttpClient http, com.fasterxml.jackson.databind.ObjectMapper mapper)	Full constructor for tests / shared HTTP.

Method Summary

Modifier and Type	Method	Description
String	twitterSearch(String query, int maxResults)
String	twitterTimeline(String userId, int maxResults)
String	twitterUser(String username)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TwitterTools

public TwitterTools()

Default constructor — picks TWITTER_BEARER_TOKEN from env.

TwitterTools

public TwitterTools(String bearerToken)

Explicit-token constructor.

TwitterTools

public TwitterTools(String bearerToken,
 okhttp3.OkHttpClient http,
 com.fasterxml.jackson.databind.ObjectMapper mapper)

Full constructor for tests / shared HTTP.

Method Details

twitterSearch

@Tool(name="twitter_search",
      description="Search recent tweets (last 7 days) via Twitter v2 API. {query} accepts the full v2 syntax: from:user, -is:retweet, lang:en, #hashtag, etc. {maxResults} clamps to [10, 100] (Twitter\'s per-call cap). Returns the raw JSON response. Requires TWITTER_BEARER_TOKEN.",
      keywords={"twitter","x","tweet","search","social"},
      idempotent=true)
public String twitterSearch(@ToolParam(description="Twitter v2 search query")
 String query,
 @ToolParam(description="Max results (10..100); 0 \u2192 default 10",required=false,defaultValue="0")
 int maxResults)
                     throws IOException

Throws:

IOException

twitterUser

@Tool(name="twitter_user",
      description="Fetch a Twitter user\'s public profile by username (without the leading @). Returns the raw JSON response with id / name / description / public_metrics. Requires TWITTER_BEARER_TOKEN.",
      keywords={"twitter","x","user","profile"},
      idempotent=true)
public String twitterUser(@ToolParam(description="Twitter username (without @)")
 String username)
                   throws IOException

Throws:

IOException

twitterTimeline

@Tool(name="twitter_timeline",
      description="Fetch a Twitter user\'s recent tweets by user id. {userId} comes from twitter_user. {maxResults} clamps to [10, 100]. Returns the raw JSON response with the user\'s recent tweets and metrics. Requires TWITTER_BEARER_TOKEN.",
      keywords={"twitter","x","timeline","user","tweets"},
      idempotent=true)
public String twitterTimeline(@ToolParam(description="Twitter user id (from twitter_user)")
 String userId,
 @ToolParam(description="Max tweets (10..100); 0 \u2192 default 10",required=false,defaultValue="0")
 int maxResults)
                       throws IOException

Throws:

IOException