@xquik/tweetclaw 1.1.0 → 1.2.1

package/README.md

@@ -43,21 +43,21 @@ AI uses explore → filters spec by category "composition"
 
 ### `tweetclaw` (execute API calls)
 
-Execute authenticated API calls. Auth is injected automatically  - the LLM never sees your API key.
+Execute authenticated API calls. Auth is injected automatically - the LLM never sees your API key.
 
 ```
-You: "Search tweets about AI agents"
+You: "Post a tweet saying 'Hello from TweetClaw!'"
 
-AI uses explore → finds /api/v1/x/tweets/search
-AI uses tweetclaw → calls the endpoint with auth
-→ Returns tweet results
+AI uses tweetclaw → finds connected account, posts tweet
+→ Returns { tweetId, success: true }
 ```
 
 ```
-You: "Post a tweet saying 'Hello from TweetClaw!'"
+You: "Search tweets about AI agents"
 
-AI uses tweetclaw → finds connected account, posts tweet
-→ Returns { tweetId, success: true }
+AI uses explore → finds /api/v1/x/tweets/search
+AI uses tweetclaw → calls the endpoint with auth
+→ Returns tweet results
 ```
 
 ## Commands

package/openclaw.plugin.json

@@ -1,6 +1,7 @@
 {
   "id": "tweetclaw",
   "name": "TweetClaw",
+  "version": "1.2.1",
   "description": "Post tweets, reply, like, retweet, follow, DM from your chat - full X/Twitter automation powered by Xquik",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xquik/tweetclaw",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Post tweets, reply, like, retweet, follow, DM & more from OpenClaw - full X/Twitter automation via Xquik",
   "license": "MIT",
   "type": "module",
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@sinclair/typebox": "^0.34.0",
+    "@sinclair/typebox": "^0.34.48",
     "@types/node": "^25.5.0",
     "@typescript-eslint/eslint-plugin": "^8.57.0",
     "@typescript-eslint/parser": "^8.57.0",

package/skills/tweetclaw/SKILL.md

@@ -11,7 +11,7 @@ read_when:
   - Extracting bulk data from X/Twitter (followers, replies, communities)
   - Downloading tweet media or uploading images
   - Sending DMs or updating X/Twitter profile
-metadata: {"openclaw":{"emoji":"🐦","primaryEnv":"XQUIK_API_KEY","requires":{"env":["XQUIK_API_KEY"]}}}
+metadata: {"openclaw":{"emoji":"🐦","primaryEnv":"XQUIK_API_KEY","requires":{"env":["XQUIK_API_KEY"]},"tags":["twitter","x","automation","social-media","tweets","scraping","giveaway","monitoring","rest-api"]}}
 ---
 
 # TweetClaw
@@ -22,6 +22,27 @@ OpenClaw plugin for X/Twitter automation powered by Xquik. Install via:
 openclaw plugins install @xquik/tweetclaw
 ```
 
+## When to Use
+
+Use TweetClaw when the user wants to:
+
+- Post tweets, reply to tweets, or delete tweets
+- Like, retweet, or follow/unfollow users
+- Send DMs on X/Twitter
+- Update their X profile, avatar, or banner
+- Upload media and tweet with images
+- Search tweets or look up user profiles
+- Extract bulk data (followers, replies, communities, spaces)
+- Run giveaway draws from tweet replies
+- Monitor X accounts for new activity
+- Compose algorithm-optimized tweets
+- Analyze a user's writing style
+- Check trending topics on X
+- Download tweet media (images, videos, GIFs)
+- Set up Telegram alerts for monitor events
+
+Do NOT use TweetClaw for browsing X in a browser, analytics dashboards, scheduling future posts, or managing X ads.
+
 ## Configuration
 
 Set your Xquik API key (get one at [xquik.com/account-manager](https://xquik.com/account-manager)):
@@ -50,12 +71,15 @@ async () => spec.endpoints.filter(e => e.category === 'composition')
 
 Execute authenticated API calls. Auth is injected automatically.
 
-Example: "Search tweets about AI agents"
+Example: "Post a tweet saying 'Hello from TweetClaw!'"
 
 ```javascript
 async () => {
-  const results = await xquik.request('/api/v1/x/tweets/search', { query: { q: 'AI agents' } });
-  return results;
+  const { accounts } = await xquik.request('/api/v1/x/accounts');
+  return xquik.request('/api/v1/x/tweets', {
+    method: 'POST',
+    body: { account: accounts[0].xUsername, text: 'Hello from TweetClaw!' }
+  });
 }
 ```
 
@@ -80,16 +104,49 @@ When polling is enabled (default), TweetClaw checks for new events every 60 seco
 
 ```
 You: "Post a tweet saying 'Hello from TweetClaw!'"
-Agent uses explore -> finds POST /api/v1/x/tweets
-Agent uses tweetclaw -> posts the tweet with auth
+Agent uses tweetclaw -> finds connected account, posts tweet
+```
+
+### Reply to a tweet
+
+```
+You: "Reply 'Great thread!' to this tweet: https://x.com/user/status/123"
+Agent uses tweetclaw -> posts reply with reply_to_tweet_id
+```
+
+### Like, retweet, follow
+
+```
+You: "Like and retweet this tweet, then follow the author"
+Agent uses tweetclaw -> likes tweet, retweets, looks up user ID, follows
+```
+
+### Send a DM
+
+```
+You: "DM @username saying 'Hey, let's collaborate!'"
+Agent uses tweetclaw -> looks up user ID, sends DM
+```
+
+### Update profile
+
+```
+You: "Change my bio to 'Building cool stuff' and update my avatar"
+Agent uses tweetclaw -> PATCH /api/v1/x/profile, PATCH /api/v1/x/profile/avatar
+```
+
+### Upload media and tweet with image
+
+```
+You: "Tweet 'Check this out!' with this image: https://example.com/photo.jpg"
+Agent uses tweetclaw -> uploads media, posts tweet with media_ids
 ```
 
 ### Search tweets
 
 ```
 You: "Search tweets about AI agents"
-Agent uses explore -> finds GET /api/v1/x/tweets/search
-Agent uses tweetclaw -> calls the endpoint
+Agent uses tweetclaw -> calls search endpoint with query
 ```
 
 ### Run a giveaway draw
@@ -99,6 +156,13 @@ You: "Pick 3 random winners from replies to this tweet: https://x.com/..."
 Agent uses tweetclaw -> creates draw with filters
 ```
 
+### Extract bulk data
+
+```
+You: "Extract the last 1000 followers of @elonmusk"
+Agent uses tweetclaw -> estimates cost, creates extraction job
+```
+
 ### Monitor an account
 
 ```
@@ -106,11 +170,32 @@ You: "Monitor @elonmusk for new tweets and follower changes"
 Agent uses tweetclaw -> creates monitor with event types
 ```
 
-### Compose an optimized tweet
+### Download tweet media
+
+```
+You: "Download all media from this tweet"
+Agent uses tweetclaw -> returns gallery URL with all media
+```
+
+### Compose an optimized tweet (free)
+
+```
+You: "Help me write a tweet about our product launch"
+Agent uses tweetclaw -> 3-step compose/refine/score workflow
+```
+
+### Analyze writing style (free)
+
+```
+You: "Analyze @username's tweet style"
+Agent uses tweetclaw -> returns style analysis with tone, patterns, metrics
+```
+
+### Browse trending topics (free)
 
 ```
-You: "Compose a tweet about our product launch"
-Agent uses tweetclaw -> 3-step compose/refine/score workflow (free)
+You: "What's trending on X right now?"
+Agent uses tweetclaw -> returns curated trending topics from 7 sources
 ```
 
 ## API Categories
@@ -136,9 +221,13 @@ Subscription ($20/month): write actions, search, media, extractions, draws, moni
 
 When a paid endpoint returns 402, TweetClaw provides a checkout URL.
 
-## When NOT to Use
+## Tips
 
-- Reading tweets in a browser or basic browsing (use a browser skill instead)
-- X/Twitter analytics dashboards (TweetClaw returns raw data, not visualizations)
-- Scheduling tweets for future posting (Xquik posts immediately)
-- Managing X/Twitter ads or promoted content (not supported)
+- Use `explore` first to discover endpoints before calling `tweetclaw` - saves tokens and avoids guessing
+- Free endpoints (compose, styles, radar, drafts) work without a subscription - always try them first
+- Never combine free and paid API calls in the same `Promise.all` - a 402 on one call kills all results
+- For write actions (post, like, follow, DM), always pass the `account` parameter with the X username
+- Follow/unfollow/DM require a numeric user ID - look up the user first via `/api/v1/x/users/:username`
+- On 402 errors, call `POST /api/v1/subscribe` to get a checkout URL instead of giving up
+- Use `/xstatus` to quickly check subscription and usage without invoking the AI agent
+- The compose workflow (compose/refine/score) is free and helps draft high-engagement tweets

package/src/index.ts

@@ -15,66 +15,64 @@ function isPollerEvent(value: unknown): value is PollerEvent {
   return typeof value === 'object' && value !== null;
 }
 
+function isPluginConfig(value: unknown): value is PluginConfig {
+  return typeof value === 'object' && value !== null && 'apiKey' in value;
+}
+
 const DEFAULT_POLLING_INTERVAL_SECONDS = 60;
 
+interface ToolResult {
+  readonly content: ReadonlyArray<{ readonly text: string; readonly type: string }>;
+  readonly isError?: true;
+}
+
 interface CommandContext {
   readonly args?: string;
+  readonly commandBody?: string;
+  readonly senderId?: string;
 }
 
 interface OpenClawApi {
-  readonly config: {
-    readonly plugins?: {
-      readonly entries?: {
-        readonly tweetclaw?: {
-          readonly config?: PluginConfig;
-        };
-      };
-    };
-  };
   readonly logger: {
+    readonly debug?: (message: string) => void;
+    readonly error: (message: string) => void;
     readonly info: (message: string) => void;
     readonly warn: (message: string) => void;
   };
+  readonly pluginConfig?: Readonly<Record<string, unknown>>;
   readonly registerCommand: (options: {
-    readonly acceptsArguments?: boolean;
+    readonly acceptsArgs?: boolean;
     readonly description: string;
     readonly handler: (context: CommandContext) => Promise<{ readonly text: string }>;
     readonly name: string;
   }) => void;
   readonly registerService: (options: {
     readonly id: string;
-    readonly start: () => void;
-    readonly stop: () => void;
+    readonly start: (context?: unknown) => void;
+    readonly stop?: (context?: unknown) => void;
   }) => void;
   readonly registerTool: (
-    options: {
+    tool: {
       readonly description: string;
+      readonly execute: (toolCallId: string, params: { readonly code: string }) => Promise<ToolResult>;
       readonly name: string;
-      readonly parameters: {
-        readonly properties: Readonly<Record<string, { readonly description: string; readonly type: string }>>;
-        readonly required: readonly string[];
-        readonly type: string;
-      };
+      readonly parameters: unknown;
     },
-    handler: (params: { readonly code: string }) => Promise<{
-      readonly content: ReadonlyArray<{ readonly text: string; readonly type: string }>;
-      readonly isError?: true;
-    }>,
+    options?: { readonly name?: string; readonly optional?: boolean },
   ) => void;
-  readonly sendMessage: (text: string) => void;
 }
 
 const CODE_PARAMETER = {
   properties: {
     code: { description: 'Async arrow function to execute', type: 'string' },
   },
-  required: ['code'] as const,
+  required: ['code'],
   type: 'object',
 };
 
 export default function register(api: OpenClawApi, fetchFunction?: FetchFunction): void {
-  const config = api.config.plugins?.entries?.tweetclaw?.config;
-  if (config?.apiKey === undefined) {
+  const config: unknown = api.pluginConfig;
+  if (!isPluginConfig(config)) {
     api.logger.warn(
       "TweetClaw: No API key configured. Run: openclaw config set plugins.entries.tweetclaw.config.apiKey 'xq_YOUR_KEY'",
     );
@@ -84,23 +82,25 @@ export default function register(api: OpenClawApi, fetchFunction?: FetchFunction
   const { apiKey, baseUrl = 'https://xquik.com' } = config;
   const request = createProxiedRequest(baseUrl, apiKey, fetchFunction);
 
-  // --- Tools (2-tool approach) ---
+  // --- Tools (2-tool approach, execute inside tool object) ---
   api.registerTool(
     {
       description: SEARCH_DESCRIPTION,
+      execute: async (_toolCallId, { code }) => handleExplore(code),
       name: 'explore',
       parameters: CODE_PARAMETER,
     },
-    async ({ code }) => handleExplore(code),
+    { name: 'explore' },
   );
 
   api.registerTool(
     {
       description: EXECUTE_DESCRIPTION,
+      execute: async (_toolCallId, { code }) => handleTweetclaw({ apiKey, baseUrl, code, fetchFunction }),
       name: 'tweetclaw',
       parameters: CODE_PARAMETER,
     },
-    async ({ code }) => handleTweetclaw({ apiKey, baseUrl, code, fetchFunction }),
+    { name: 'tweetclaw', optional: true },
   );
 
   // --- Commands (instant, no LLM) ---
@@ -114,7 +114,7 @@ export default function register(api: OpenClawApi, fetchFunction?: FetchFunction
   });
 
   api.registerCommand({
-    acceptsArguments: true,
+    acceptsArgs: true,
     description: 'Show trending topics on X',
     handler: async ({ args }) => {
       const text = await handleXTrends(request, args);
@@ -136,7 +136,7 @@ export default function register(api: OpenClawApi, fetchFunction?: FetchFunction
           const username: string = isPollerEvent(event) && typeof event.xUsername === 'string'
             ? event.xUsername
             : '';
-          api.sendMessage(`[TweetClaw] ${eventType} from @${username}`);
+          api.logger.info(`[TweetClaw] ${eventType} from @${username}`);
         }
       },
       request,

package/src/tools/explore.ts

@@ -4,7 +4,7 @@ import type { EndpointInfo, ToolResult } from '../types.js';
 
 const categories = [...new Set(API_SPEC.map((endpoint) => endpoint.category))].toSorted((a, b) => a.localeCompare(b)).join(', ');
 
-const SEARCH_DESCRIPTION = `Search the X (Twitter) API spec for endpoints: tweet search, user lookup, media download, monitoring, giveaways, composition, and more. No network calls - runs against an in-memory endpoint catalog.
+const SEARCH_DESCRIPTION = `Search the X (Twitter) API spec for endpoints: post tweets, reply, like, retweet, follow, DM, update profile, upload media, search tweets, look up users, extract data, monitor accounts, run giveaways, compose tweets, and more. No network calls - runs against an in-memory endpoint catalog.
 
 Write an async arrow function. The sandbox provides:
 

package/src/tools/tweetclaw.ts

@@ -2,7 +2,7 @@ import { createProxiedRequest } from '../request.js';
 import { AsyncFunction, errorResult, specEndpoints, successResult } from './sandbox.js';
 import type { FetchFunction, RequestFunction, ToolResult } from '../types.js';
 
-const EXECUTE_DESCRIPTION = `Execute X (Twitter) API calls: search tweets, look up users, download media, compose tweets, run giveaways, monitor accounts, and more. Write an async arrow function.
+const EXECUTE_DESCRIPTION = `Execute X (Twitter) API calls: post tweets, reply, like, retweet, follow, DM, update profile, upload media, search tweets, look up users, extract data, run giveaways, monitor accounts, compose tweets, and more. Write an async arrow function.
 
 The sandbox provides:
 \`\`\`typescript
@@ -20,6 +20,13 @@ declare const spec: { endpoints: EndpointInfo[] };
 Auth is injected automatically - never pass API keys.
 First use "explore" to find endpoints, then write code here to call them.
 
+## Important rules
+- TWEET ACTIONS: SENDING a tweet ("tweet this", "post this") uses POST /api/v1/x/tweets. DRAFTING a tweet ("help me write", "compose") uses the 3-step compose flow. Never use compose when the user has text and wants to send it.
+- CALL ORDERING: NEVER combine free and paid endpoints in Promise.all. Call free endpoints first (radar, styles, compose), then paid ones separately. If a paid call fails with 402, still use free data already fetched.
+- WRITE ACTIONS: All require the "account" parameter (X username, e.g. "@myaccount"). Follow/unfollow/DM use numeric user ID in path - look up the user first via GET /api/v1/x/users/:username.
+- CURRENT EVENTS: Use /api/v1/radar (free) for trending topics. Never use web search for trends.
+- SUBSCRIPTION ERRORS: On 402, call POST /api/v1/subscribe (free) to get checkout URL.
+
 ## Workflows
 
 ### 1. Send a tweet (Subscription required)
@@ -103,7 +110,28 @@ async () => {
 }
 \`\`\`
 
-### 7. Search tweets with pagination (Subscription required)
+### 7. Update profile, avatar, or banner
+\`\`\`javascript
+async () => {
+  // Update bio, name, location, URL
+  await xquik.request('/api/v1/x/profile', {
+    method: 'PATCH',
+    body: { account: '@myaccount', name: 'New Name', bio: 'Building cool stuff' }
+  });
+  // Update avatar (url must be HTTPS, max 700 KB)
+  await xquik.request('/api/v1/x/profile/avatar', {
+    method: 'PATCH',
+    body: { account: '@myaccount', url: 'https://example.com/avatar.jpg' }
+  });
+  // Update banner (max 2 MB)
+  return xquik.request('/api/v1/x/profile/banner', {
+    method: 'PATCH',
+    body: { account: '@myaccount', url: 'https://example.com/banner.jpg' }
+  });
+}
+\`\`\`
+
+### 8. Search tweets with pagination (Subscription required)
 \`\`\`javascript
 async () => {
   // Use limit param for more than 20 results (max 200)
@@ -113,14 +141,87 @@ async () => {
 }
 \`\`\`
 
-### 8. Browse trending topics (FREE)
+### 9. Look up a user or tweet
+\`\`\`javascript
+async () => {
+  // User profile (name, bio, followers, following, verified, location)
+  const user = await xquik.request('/api/v1/x/users/elonmusk');
+  // Single tweet with full metrics
+  const tweet = await xquik.request('/api/v1/x/tweets/1234567890');
+  // Check if A follows B
+  const follows = await xquik.request('/api/v1/x/followers/check', {
+    query: { source: 'userA', target: 'userB' }
+  });
+  return { user, tweet, follows };
+}
+\`\`\`
+
+### 10. Monitor an account + set up webhook
+\`\`\`javascript
+async () => {
+  // Create monitor for new tweets, replies, follower changes
+  const monitor = await xquik.request('/api/v1/monitors', {
+    method: 'POST',
+    body: { username: 'elonmusk', eventTypes: ['tweet.new', 'tweet.reply', 'follower.gained'] }
+  });
+  // Set up webhook to receive events (save the secret!)
+  const webhook = await xquik.request('/api/v1/webhooks', {
+    method: 'POST',
+    body: { url: 'https://your-server.com/webhook', eventTypes: ['tweet.new', 'tweet.reply'] }
+  });
+  return { monitor, webhook };
+}
+\`\`\`
+
+### 11. Run a giveaway draw from tweet replies
+\`\`\`javascript
+async () => {
+  return xquik.request('/api/v1/draws', {
+    method: 'POST',
+    body: {
+      tweetUrl: 'https://x.com/user/status/1234567890',
+      winnerCount: 3,
+      backupCount: 2,
+      uniqueAuthorsOnly: true,
+      mustRetweet: true,
+      mustFollowUsername: 'myaccount',
+      filterMinFollowers: 50
+    }
+  });
+}
+\`\`\`
+
+### 12. Extract bulk data (followers, replies, communities)
+\`\`\`javascript
+async () => {
+  // Always estimate cost first
+  const estimate = await xquik.request('/api/v1/extractions/estimate', {
+    method: 'POST',
+    body: { toolType: 'follower_explorer', targetUsername: 'elonmusk', resultsLimit: 1000 }
+  });
+  if (!estimate.allowed) return { error: 'Would exceed quota', estimate };
+  // Create extraction job
+  const job = await xquik.request('/api/v1/extractions', {
+    method: 'POST',
+    body: { toolType: 'follower_explorer', targetUsername: 'elonmusk', resultsLimit: 1000 }
+  });
+  return job;
+  // 20 tool types: reply_extractor, repost_extractor, quote_extractor, thread_extractor,
+  // article_extractor, follower_explorer, following_explorer, verified_follower_explorer,
+  // mention_extractor, post_extractor, community_extractor, community_moderator_explorer,
+  // community_post_extractor, community_search, list_member_extractor, list_post_extractor,
+  // list_follower_explorer, space_explorer, people_search, tweet_search_extractor
+}
+\`\`\`
+
+### 13. Browse trending topics (FREE)
 \`\`\`javascript
 async () => {
   return xquik.request('/api/v1/radar');
 }
 \`\`\`
 
-### 9. Analyze a user's writing style
+### 14. Analyze a user's writing style
 \`\`\`javascript
 async () => {
   // Returns cached style if available (free for all users)
@@ -132,7 +233,7 @@ async () => {
 }
 \`\`\`
 
-### 10. Download media and get gallery link (Subscription required)
+### 15. Download media and get gallery link (Subscription required)
 \`\`\`javascript
 async () => {
   // Returns galleryUrl only (shareable gallery page with all media)
@@ -143,14 +244,42 @@ async () => {
 }
 \`\`\`
 
-### 11. Subscribe (FREE - returns Stripe checkout URL)
+### 16. Set up Telegram alerts for monitor events (FREE)
+\`\`\`javascript
+async () => {
+  return xquik.request('/api/v1/integrations', {
+    method: 'POST',
+    body: {
+      type: 'telegram',
+      chatId: '123456789',
+      eventTypes: ['tweet.new', 'tweet.reply', 'draw.completed', 'extraction.completed']
+    }
+  });
+}
+\`\`\`
+
+### 17. Community actions (create, join, leave)
+\`\`\`javascript
+async () => {
+  // Join a community
+  await xquik.request('/api/v1/x/communities/99999/join', {
+    method: 'POST', body: { account: '@myaccount' }
+  });
+  // Leave a community
+  await xquik.request('/api/v1/x/communities/99999/join', {
+    method: 'DELETE', body: { account: '@myaccount' }
+  });
+}
+\`\`\`
+
+### 18. Subscribe (FREE - returns Stripe checkout URL)
 \`\`\`javascript
 async () => {
   return xquik.request('/api/v1/subscribe', { method: 'POST' });
 }
 \`\`\`
 
-### 12. Draft & optimize tweet text (3-step compose flow, FREE)
+### 19. Draft & optimize tweet text (3-step compose flow, FREE)
 \`\`\`javascript
 async () => {
   // Use this ONLY when the user wants help WRITING tweet text.