@xquik/tweetclaw 1.0.3 → 1.2.0

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.0",
   "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.0.3",
+  "version": "1.2.0",
   "description": "Post tweets, reply, like, retweet, follow, DM & more from OpenClaw - full X/Twitter automation via Xquik",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
   },
   "files": [
     "src/",
+    "skills/",
     "openclaw.plugin.json"
   ],
   "keywords": [
@@ -48,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

@@ -0,0 +1,208 @@
+---
+name: tweetclaw
+description: "OpenClaw plugin for X/Twitter automation. Post tweets, reply, like, retweet, follow, DM, search, extract data, run giveaways, monitor accounts via Xquik. 40+ endpoints, 2 tools (explore + tweetclaw), 2 commands (/xstatus, /xtrends), background event poller."
+homepage: https://xquik.com
+read_when:
+  - Posting, replying, liking, retweeting, or following on X/Twitter
+  - Searching tweets or looking up X/Twitter users
+  - Running giveaway draws from tweet replies
+  - Monitoring X/Twitter accounts for new activity
+  - Composing algorithm-optimized tweets
+  - 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"]}}}
+---
+
+# TweetClaw
+
+OpenClaw plugin for X/Twitter automation powered by Xquik. Install via:
+
+```bash
+openclaw plugins install @xquik/tweetclaw
+```
+
+## Configuration
+
+Set your Xquik API key (get one at [xquik.com/account-manager](https://xquik.com/account-manager)):
+
+```bash
+openclaw config set plugins.entries.tweetclaw.config.apiKey 'xq_YOUR_KEY'
+```
+
+## Tools
+
+TweetClaw registers 2 tools that cover the entire Xquik API (40+ endpoints):
+
+### `explore` (free, no network)
+
+Search the API spec to find endpoints. No API calls are made.
+
+Example: "What endpoints are available for tweet composition?"
+
+The agent writes an async arrow function that filters the in-memory endpoint catalog:
+
+```javascript
+async () => spec.endpoints.filter(e => e.category === 'composition')
+```
+
+### `tweetclaw` (execute API calls)
+
+Execute authenticated API calls. Auth is injected automatically.
+
+Example: "Post a tweet saying 'Hello from TweetClaw!'"
+
+```javascript
+async () => {
+  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!' }
+  });
+}
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/xstatus` | Account info, subscription status, usage |
+| `/xtrends` | Trending topics from curated sources |
+| `/xtrends tech` | Trending topics filtered by category |
+
+## Event Notifications
+
+When polling is enabled (default), TweetClaw checks for new events every 60 seconds:
+
+- Monitor alerts: new tweets, replies, quotes, retweets from monitored accounts
+- Follower changes: gained or lost followers on monitored accounts
+
+## Common Workflows
+
+### Post a tweet
+
+```
+You: "Post a tweet saying 'Hello from TweetClaw!'"
+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 tweetclaw -> calls search endpoint with query
+```
+
+### Run a giveaway draw
+
+```
+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
+
+```
+You: "Monitor @elonmusk for new tweets and follower changes"
+Agent uses tweetclaw -> creates monitor with event types
+```
+
+### 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: "What's trending on X right now?"
+Agent uses tweetclaw -> returns curated trending topics from 7 sources
+```
+
+## API Categories
+
+| Category | Examples | Free |
+|----------|---------|------|
+| Write Actions | Post tweets, reply, like, retweet, follow, DM, update profile | No |
+| Media | Upload media, download tweet media | No |
+| Twitter | Search tweets, look up users, check follows | No |
+| Composition | Compose, refine, score tweets; manage drafts | Yes |
+| Styles | Analyze tweet styles, compare, performance | Mixed |
+| Extraction | Reply/follower/community extraction (20 tools) | No |
+| Draws | Giveaway draws, export results | No |
+| Monitoring | Create monitors, view events, webhooks | No |
+| Account | API keys, subscription, connected X accounts | Yes |
+| Trends | X trending topics, curated radar from 7 sources | Mixed |
+
+## Pricing
+
+Free tier (no subscription): tweet composition, style analysis, drafts, curated radar, account management, integrations.
+
+Subscription ($20/month): write actions, search, media, extractions, draws, monitors, X trending.
+
+When a paid endpoint returns 402, TweetClaw provides a checkout URL.
+
+## When NOT to Use
+
+- 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)

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.