@xquik/tweetclaw 1.6.4 → 1.6.6

package/src/index.ts

@@ -1,11 +1,13 @@
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
 import { handleXStatus } from './commands/xstatus.js';
 import { handleXTrends } from './commands/xtrends.js';
 import { initMpp } from './mpp.js';
 import { createProxiedRequest } from './request.js';
 import { createEventPoller } from './services/event-poller.js';
+import { normalizeMethod, requestNeedsApproval } from './tools/catalog.js';
 import { handleExplore, SEARCH_DESCRIPTION } from './tools/explore.js';
 import { EXECUTE_DESCRIPTION, handleTweetclaw } from './tools/tweetclaw.js';
-import type { FetchFunction, PluginConfig } from './types.js';
+import type { ExploreParams, FetchFunction, PluginConfig, TweetclawParams } from './types.js';
 
 interface PollerEvent {
   readonly eventType?: string;
@@ -23,6 +25,34 @@ function isPluginConfig(value: unknown): value is PluginConfig {
 
 const DEFAULT_POLLING_INTERVAL_SECONDS = 60;
 
+const CONFIG_SCHEMA = {
+  additionalProperties: false,
+  anyOf: [
+    { required: ['apiKey'] },
+    { required: ['tempoSigningKey'] },
+  ],
+  properties: {
+    apiKey: {
+      description: 'Xquik API key (get one at dashboard.xquik.com). Required for account-backed X automation.',
+      minLength: 1,
+      type: 'string',
+    },
+    baseUrl: { default: 'https://xquik.com', type: 'string' },
+    pollingEnabled: { default: true, type: 'boolean' },
+    pollingInterval: {
+      default: 60,
+      description: 'Event polling interval in seconds',
+      type: 'number',
+    },
+    tempoSigningKey: {
+      description: 'MPP signing key for pay-per-use mode. No account needed. 32 read-only X-API endpoints.',
+      minLength: 1,
+      type: 'string',
+    },
+  },
+  type: 'object',
+};
+
 interface ToolResult {
   readonly content: ReadonlyArray<{ readonly text: string; readonly type: string }>;
   readonly isError?: true;
@@ -34,6 +64,28 @@ interface CommandContext {
   readonly senderId?: string;
 }
 
+interface BeforeToolCallEvent {
+  readonly params?: unknown;
+  readonly toolName?: string;
+}
+
+interface ToolApprovalRequest {
+  readonly description: string;
+  readonly pluginId?: string;
+  readonly severity?: 'critical' | 'info' | 'warning';
+  readonly timeoutBehavior?: 'allow' | 'deny';
+  readonly timeoutMs?: number;
+  readonly title: string;
+}
+
+interface BeforeToolCallResult {
+  readonly requireApproval?: ToolApprovalRequest;
+}
+
+type BeforeToolCallHandler = (
+  event: BeforeToolCallEvent,
+) => BeforeToolCallResult | Promise<BeforeToolCallResult | undefined> | undefined;
+
 interface OpenClawApi {
   readonly logger: {
     readonly debug?: (message: string) => void;
@@ -56,23 +108,152 @@ interface OpenClawApi {
   readonly registerTool: (
     tool: {
       readonly description: string;
-      readonly execute: (toolCallId: string, params: { readonly code: string }) => Promise<ToolResult>;
+      readonly execute: (toolCallId: string, params: unknown) => Promise<ToolResult>;
       readonly name: string;
       readonly parameters: unknown;
     },
     options?: { readonly name?: string; readonly optional?: boolean },
   ) => void;
+  readonly on?: (
+    name: 'before_tool_call',
+    handler: BeforeToolCallHandler,
+    options?: { readonly priority?: number },
+  ) => void;
+  readonly registerHook?: (
+    name: 'before_tool_call',
+    handler: BeforeToolCallHandler,
+    options?: { readonly priority?: number },
+  ) => void;
 }
 
-const CODE_PARAMETER = {
+const EXPLORE_PARAMETERS = {
+  properties: {
+    category: { description: 'Endpoint category filter', type: 'string' },
+    free: { description: 'Filter by free or paid endpoints', type: 'boolean' },
+    limit: { default: 25, description: 'Maximum endpoint descriptors to return', maximum: 100, minimum: 1, type: 'number' },
+    method: { description: 'HTTP method filter', enum: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE'], type: 'string' },
+    mpp: { description: 'Filter by MPP eligibility', type: 'boolean' },
+    path: { description: 'Exact or partial API path filter', type: 'string' },
+    query: { description: 'Keyword search across endpoint metadata', type: 'string' },
+  },
+  type: 'object',
+};
+
+const TWEETCLAW_PARAMETERS = {
+  additionalProperties: false,
   properties: {
-    code: { description: 'Async arrow function to execute', type: 'string' },
+    body: { description: 'JSON request body', type: ['object', 'array', 'string', 'number', 'boolean', 'null'] },
+    method: { default: 'GET', description: 'HTTP method', enum: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE'], type: 'string' },
+    path: { description: 'Concrete /api/v1/... endpoint path from the catalog', type: 'string' },
+    query: {
+      additionalProperties: { type: ['string', 'number', 'boolean'] },
+      description: 'Query parameters',
+      type: 'object',
+    },
   },
-  required: ['code'],
+  required: ['path'],
   type: 'object',
 };
 
-export default function register(api: OpenClawApi, fetchFunction?: FetchFunction): void {
+function asObject(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+  return Object.fromEntries(Object.entries(value));
+}
+
+function asExploreParams(params: unknown): Readonly<ExploreParams> {
+  const value = asObject(params);
+  if (value === undefined) return {};
+
+  return {
+    ...(typeof value.category === 'string' ? { category: value.category } : {}),
+    ...(typeof value.free === 'boolean' ? { free: value.free } : {}),
+    ...(typeof value.limit === 'number' ? { limit: value.limit } : {}),
+    ...(typeof value.method === 'string' ? { method: value.method } : {}),
+    ...(typeof value.mpp === 'boolean' ? { mpp: value.mpp } : {}),
+    ...(typeof value.path === 'string' ? { path: value.path } : {}),
+    ...(typeof value.query === 'string' ? { query: value.query } : {}),
+  };
+}
+
+function asQueryParams(value: unknown): Readonly<Record<string, boolean | number | string>> | undefined {
+  const query = asObject(value);
+  if (query === undefined) return undefined;
+
+  const entries = Object.entries(query).filter(
+    (entry): entry is [string, boolean | number | string] =>
+      ['boolean', 'number', 'string'].includes(typeof entry[1]),
+  );
+  return Object.fromEntries(entries);
+}
+
+function asTweetclawParams(params: unknown): Readonly<TweetclawParams> {
+  const value = asObject(params);
+  if (value === undefined || typeof value.path !== 'string') {
+    return { path: '' };
+  }
+
+  const query = asQueryParams(value.query);
+  return {
+    ...(value.body === undefined ? {} : { body: value.body }),
+    ...(typeof value.method === 'string' ? { method: value.method } : {}),
+    path: value.path,
+    ...(query === undefined ? {} : { query }),
+  };
+}
+
+function toolCallParams(event: BeforeToolCallEvent): Readonly<TweetclawParams> | undefined {
+  const params = asTweetclawParams(event.params);
+  if (params.path.length === 0) {
+    return undefined;
+  }
+  return params;
+}
+
+function requiresTweetclawApproval(params: Readonly<TweetclawParams>): boolean {
+  return requestNeedsApproval(normalizeMethod(params.method), params.path);
+}
+
+function registerWriteApprovalHook(api: OpenClawApi): void {
+  const registerHook = api.on ?? api.registerHook;
+  if (registerHook === undefined) {
+    api.logger.warn(
+      'TweetClaw: OpenClaw approval hooks are unavailable. Keep explicit user approval before write actions.',
+    );
+    return;
+  }
+
+  registerHook.call(
+    api,
+    'before_tool_call',
+    (event): BeforeToolCallResult | undefined => {
+      if (event.toolName !== 'tweetclaw') {
+        return undefined;
+      }
+
+      const params = toolCallParams(event);
+      if (params === undefined || !requiresTweetclawApproval(params)) {
+        return undefined;
+      }
+
+      return {
+        requireApproval: {
+          description:
+            'TweetClaw is about to invoke an endpoint that can change X accounts, create jobs, or expose private data. Review the tool call before allowing it.',
+          pluginId: 'tweetclaw',
+          severity: 'warning',
+          timeoutBehavior: 'deny',
+          timeoutMs: 60_000,
+          title: 'Approve TweetClaw Action',
+        },
+      };
+    },
+    { priority: 50 },
+  );
+}
+
+function register(api: OpenClawApi, fetchFunction?: FetchFunction): void {
   const config: unknown = api.pluginConfig;
   if (!isPluginConfig(config)) {
     api.logger.warn(
@@ -98,14 +279,18 @@ export default function register(api: OpenClawApi, fetchFunction?: FetchFunction
   }
 
   const request = createProxiedRequest(baseUrl, credential, fetchFunction);
+  registerWriteApprovalHook(api);
 
   // --- Tools (2-tool approach, execute inside tool object) ---
   api.registerTool(
     {
       description: SEARCH_DESCRIPTION,
-      execute: async (_toolCallId, { code }) => handleExplore(code),
+      execute: async (_toolCallId, params) => {
+        await Promise.resolve();
+        return handleExplore(asExploreParams(params));
+      },
       name: 'explore',
-      parameters: CODE_PARAMETER,
+      parameters: EXPLORE_PARAMETERS,
     },
     { name: 'explore' },
   );
@@ -113,9 +298,15 @@ export default function register(api: OpenClawApi, fetchFunction?: FetchFunction
   api.registerTool(
     {
       description: EXECUTE_DESCRIPTION,
-      execute: async (_toolCallId, { code }) => handleTweetclaw({ apiKey: credential, baseUrl, code, fetchFunction }),
+      execute: async (_toolCallId, params) => handleTweetclaw({
+        apiKey: credential,
+        baseUrl,
+        fetchFunction,
+        mppMode: isMppMode,
+        params: asTweetclawParams(params),
+      }),
       name: 'tweetclaw',
-      parameters: CODE_PARAMETER,
+      parameters: TWEETCLAW_PARAMETERS,
     },
     { name: 'tweetclaw', optional: true },
   );
@@ -170,3 +361,14 @@ export default function register(api: OpenClawApi, fetchFunction?: FetchFunction
 
   api.logger.info('TweetClaw: Plugin registered successfully');
 }
+
+const plugin = definePluginEntry({
+  configSchema: CONFIG_SCHEMA,
+  description: 'Structured X/Twitter automation through Xquik',
+  id: 'tweetclaw',
+  name: 'TweetClaw',
+  register,
+});
+
+export { register };
+export default plugin;

package/src/mpp.ts

@@ -1,5 +1,3 @@
-import { resolveAsyncFunctionConstructor } from './tools/executor.js';
-
 type ModuleLoader = (name: string) => Promise<Record<string, unknown>>;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -10,16 +8,16 @@ function isCallable(value: unknown): value is (...args: readonly unknown[]) => u
   return typeof value === 'function';
 }
 
+async function loadDynamicModule(name: string): Promise<Record<string, unknown>> {
+  const mod: unknown = await import(name);
+  if (!isRecord(mod)) {
+    throw new Error(`Failed to load ${name}`);
+  }
+  return mod;
+}
+
 function createModuleLoader(): ModuleLoader {
-  const loader = resolveAsyncFunctionConstructor();
-  const dynamicImport = new loader('n', 'return import(n)');
-  return async (name: string): Promise<Record<string, unknown>> => {
-    const mod: unknown = await dynamicImport(name);
-    if (!isRecord(mod)) {
-      throw new Error(`Failed to load ${name}`);
-    }
-    return mod;
-  };
+  return loadDynamicModule;
 }
 
 async function initMpp(tempoSigningKey: string, loadModule?: ModuleLoader): Promise<void> {

package/src/request.ts

@@ -7,6 +7,7 @@ const AUTHORIZATION_HEADER = 'authorization';
 const BEARER_PREFIX = 'Bearer ';
 const API_KEY_PREFIX = 'xq_';
 const API_V1_PREFIX = '/api/v1/';
+const SUPPORT_TICKETS_PREFIX = '/api/v1/support/tickets';
 
 function buildAuthHeader(credential: string): Record<string, string> {
   if (credential.startsWith(API_KEY_PREFIX)) {
@@ -34,18 +35,42 @@ function buildFetchUrl(baseUrl: string, path: string, query?: Readonly<Record<st
 }
 
 const PROHIBITED_PATHS: ReadonlyArray<readonly [string, string]> = [
+  ['PATCH', '/api/v1/account'],
+  ['PUT', '/api/v1/account/x-identity'],
+  ['GET', '/api/v1/api-keys'],
+  ['POST', '/api/v1/api-keys'],
+  ['POST', '/api/v1/credits/topup'],
+  ['GET', '/api/v1/credits/topup/status'],
+  ['POST', '/api/v1/credits/quick-topup'],
+  ['POST', '/api/v1/subscribe'],
   ['POST', '/api/v1/x/accounts'],
   ['POST', '/api/v1/x/accounts/'],
+  ['POST', '/api/v1/x/accounts/bulk-retry'],
 ];
 
-const PROHIBITED_PATH_PATTERN = /^\/api\/v1\/x\/accounts\/[^/]+\/reauth\/?$/;
+const PROHIBITED_PATH_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
+  ['DELETE', /^\/api\/v1\/api-keys\/[^/]+\/?$/u],
+  ['DELETE', /^\/api\/v1\/x\/accounts\/[^/]+\/?$/u],
+  ['GET', /^\/api\/v1\/x\/accounts\/[^/]+\/?$/u],
+  ['POST', /^\/api\/v1\/x\/accounts\/[^/]+\/reauth\/?$/u],
+];
+
+const SUPPORT_TICKET_METHODS: ReadonlySet<string> = new Set(['GET', 'PATCH', 'POST']);
+
+function isSupportTicketPath(method: string, path: string): boolean {
+  return SUPPORT_TICKET_METHODS.has(method)
+    && (path === SUPPORT_TICKETS_PREFIX || path.startsWith(`${SUPPORT_TICKETS_PREFIX}/`));
+}
 
 function isProhibitedRequest(method: string, path: string): boolean {
   const upperMethod = method.toUpperCase();
   const matchesStaticPath = PROHIBITED_PATHS.some(
     ([blockedMethod, blockedPath]) => upperMethod === blockedMethod && path === blockedPath,
   );
-  return matchesStaticPath || (upperMethod === 'POST' && PROHIBITED_PATH_PATTERN.test(path));
+  const matchesPattern = PROHIBITED_PATH_PATTERNS.some(
+    ([blockedMethod, pattern]) => upperMethod === blockedMethod && pattern.test(path),
+  );
+  return matchesStaticPath || matchesPattern || isSupportTicketPath(upperMethod, path);
 }
 
 function validateRequestPath(method: string, path: string): void {

package/src/tools/catalog.ts

@@ -0,0 +1,145 @@
+import { API_SPEC } from '../api-spec.js';
+import type { EndpointInfo, ExploreParams, TweetclawParams } from '../types.js';
+
+const API_V1_PREFIX = '/api/v1/';
+const DEFAULT_EXPLORE_LIMIT = 25;
+const MAX_EXPLORE_LIMIT = 100;
+
+const specEndpoints: readonly EndpointInfo[] = API_SPEC.filter((endpoint) => endpoint.agentProhibited !== true);
+
+function normalizeMethod(method?: string): string {
+  return (method ?? 'GET').toUpperCase();
+}
+
+function normalizeLimit(limit?: number): number {
+  if (limit === undefined || !Number.isFinite(limit)) {
+    return DEFAULT_EXPLORE_LIMIT;
+  }
+  return Math.min(Math.max(Math.trunc(limit), 1), MAX_EXPLORE_LIMIT);
+}
+
+function pathSegments(path: string): readonly string[] {
+  const normalized = path.endsWith('/') ? path.slice(0, -1) : path;
+  return normalized.split('/');
+}
+
+function matchesEndpointPath(endpointPath: string, requestPath: string): boolean {
+  if (endpointPath === requestPath) return true;
+  const endpointSegments = pathSegments(endpointPath);
+  const requestSegments = pathSegments(requestPath);
+  if (endpointSegments.length !== requestSegments.length) return false;
+
+  return endpointSegments.every((segment, index) => {
+    const requestSegment = String(requestSegments.at(index));
+    return segment.startsWith(':') ? requestSegment.length > 0 : segment === requestSegment;
+  });
+}
+
+function assertSafePath(path: string): void {
+  if (!path.startsWith(API_V1_PREFIX)) {
+    throw new Error(`Path must start with /api/v1/ but got: ${path}`);
+  }
+  if (path.includes('?') || path.includes('#')) {
+    throw new Error('Pass query parameters through the query object, not in the path.');
+  }
+}
+
+function findEndpoint(method: string, path: string): EndpointInfo | undefined {
+  return specEndpoints.find(
+    (endpoint) => endpoint.method === method && matchesEndpointPath(endpoint.path, path),
+  );
+}
+
+function normalizeQuery(query?: Readonly<Record<string, boolean | number | string>>): Readonly<Record<string, string>> | undefined {
+  if (query === undefined) return undefined;
+  return Object.fromEntries(Object.entries(query).map(([key, value]) => [key, String(value)]));
+}
+
+function requestNeedsApproval(method: string, path: string): boolean {
+  if (method !== 'GET') {
+    return true;
+  }
+
+  return path.startsWith('/api/v1/events')
+    || path.startsWith('/api/v1/webhooks')
+    || path === '/api/v1/x/accounts'
+    || path.startsWith('/api/v1/x/accounts/')
+    || path.startsWith('/api/v1/x/bookmarks')
+    || path.startsWith('/api/v1/x/dm/')
+    || path.startsWith('/api/v1/x/notifications')
+    || path.startsWith('/api/v1/x/timeline');
+}
+
+function resolveCatalogRequest(
+  params: Readonly<TweetclawParams>,
+  options?: Readonly<{ mppMode?: boolean }>,
+): {
+  readonly body?: unknown;
+  readonly endpoint: EndpointInfo;
+  readonly method: string;
+  readonly path: string;
+  readonly query?: Readonly<Record<string, string>>;
+} {
+  const method = normalizeMethod(params.method);
+  const { body, path } = params;
+  assertSafePath(path);
+  const endpoint = findEndpoint(method, path);
+  if (endpoint === undefined) {
+    throw new Error(`Endpoint is not in the TweetClaw catalog: ${method} ${path}`);
+  }
+  if (options?.mppMode === true && endpoint.mpp === undefined) {
+    throw new Error(`Endpoint is not available in MPP mode: ${method} ${endpoint.path}`);
+  }
+
+  const query = normalizeQuery(params.query);
+  if (query === undefined) {
+    return { body, endpoint, method, path };
+  }
+  return { body, endpoint, method, path, query };
+}
+
+function endpointMatchesQuery(endpoint: EndpointInfo, query: string): boolean {
+  const normalized = query.toLowerCase();
+  const { category, method, parameters, path, responseShape, summary } = endpoint;
+  const haystack = [
+    category,
+    method,
+    path,
+    responseShape,
+    summary,
+    ...(parameters ?? []).flatMap((parameter) => [
+      parameter.description,
+      parameter.name,
+      parameter.type,
+    ]),
+  ].join(' ').toLowerCase();
+
+  return haystack.includes(normalized);
+}
+
+function exploreCatalog(params: Readonly<ExploreParams> = {}): readonly EndpointInfo[] {
+  const method = params.method === undefined ? undefined : normalizeMethod(params.method);
+  const query = params.query?.trim();
+  const category = params.category?.trim().toLowerCase();
+  const path = params.path?.trim();
+  const limit = normalizeLimit(params.limit);
+
+  return specEndpoints
+    .filter((endpoint) => method === undefined || endpoint.method === method)
+    .filter((endpoint) => category === undefined || endpoint.category.toLowerCase() === category)
+    .filter((endpoint) => params.free === undefined || endpoint.free === params.free)
+    .filter((endpoint) => params.mpp === undefined || (endpoint.mpp !== undefined) === params.mpp)
+    .filter((endpoint) => path === undefined || matchesEndpointPath(endpoint.path, path) || endpoint.path.includes(path))
+    .filter((endpoint) => query === undefined || query.length === 0 || endpointMatchesQuery(endpoint, query))
+    .slice(0, limit);
+}
+
+export {
+  exploreCatalog,
+  findEndpoint,
+  matchesEndpointPath,
+  normalizeMethod,
+  requestNeedsApproval,
+  resolveCatalogRequest,
+  specEndpoints,
+};

package/src/tools/explore.ts

@@ -1,53 +1,27 @@
-import { API_SPEC } from '../api-spec.js';
-import { errorResult, runInSandbox, specEndpoints, successResult } from './executor.js';
-import type { EndpointInfo, ToolResult } from '../types.js';
+import { exploreCatalog, specEndpoints } from './catalog.js';
+import { errorResult, successResult } from './result.js';
+import type { EndpointInfo, ExploreParams, ToolResult } from '../types.js';
 
-const categories = [...new Set(API_SPEC.map((endpoint) => endpoint.category))].toSorted((a, b) => a.localeCompare(b)).join(', ');
+const categories = [...new Set(specEndpoints.map((endpoint) => endpoint.category))]
+  .toSorted((a, b) => a.localeCompare(b))
+  .join(', ');
 
-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.
+const SEARCH_DESCRIPTION = `Search the X (Twitter) API endpoint catalog. No network calls and no code execution.
 
-Write an async arrow function. The sandbox provides:
+Use structured filters:
+- query: keyword search across summaries, paths, response shapes, and parameters
+- category: one of ${categories}
+- method: GET, POST, PATCH, PUT, or DELETE
+- path: exact or partial API path
+- free: true for free endpoints, false for paid endpoints
+- mpp: true for MPP-eligible endpoints only
+- limit: 1-100 results, default 25
 
-\`\`\`typescript
-interface EndpointInfo {
-  method: string;
-  path: string;
-  summary: string;
-  category: string; // ${categories}
-  free: boolean;
-  parameters?: Array<{ name: string; in: 'query' | 'path' | 'body'; required: boolean; type: string; description: string }>;
-  responseShape?: string;
-}
-
-declare const spec: { endpoints: EndpointInfo[] };
-\`\`\`
-
-## Examples
-
-### Find all free endpoints
-\`\`\`javascript
-async () => {
-  return spec.endpoints.filter(e => e.free);
-}
-\`\`\`
-
-### Find endpoints by category
-\`\`\`javascript
-async () => {
-  return spec.endpoints.filter(e => e.category === 'composition');
-}
-\`\`\`
-
-### Search by keyword
-\`\`\`javascript
-async () => {
-  return spec.endpoints.filter(e => e.summary.toLowerCase().includes('tweet'));
-}
-\`\`\``;
+Returns endpoint descriptors with method, path, summary, category, parameters, cost, and response shape.`;
 
-async function handleExplore(code: string): Promise<ToolResult> {
+async function handleExplore(params: Readonly<ExploreParams> = {}): Promise<ToolResult> {
   try {
-    const result: unknown = await runInSandbox(code, { spec: { endpoints: specEndpoints } });
+    const result = await Promise.resolve(exploreCatalog(params));
     return successResult(result);
   } catch (error: unknown) {
     return errorResult(error);

package/src/tools/result.ts

@@ -0,0 +1,19 @@
+import { truncateResponse } from '../truncate.js';
+import type { ToolResult } from '../types.js';
+
+function extractErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.constructor.name}: ${error.message}`;
+  }
+  return String(error);
+}
+
+function successResult(content: unknown): ToolResult {
+  return { content: [{ text: truncateResponse(content), type: 'text' }] };
+}
+
+function errorResult(error: unknown): ToolResult {
+  return { content: [{ text: extractErrorMessage(error), type: 'text' }], isError: true };
+}
+
+export { errorResult, extractErrorMessage, successResult };