@xquik/tweetclaw 1.0.0

package/src/commands/xstatus.ts

@@ -0,0 +1,76 @@
+import type { RequestFunction } from '../types.js';
+
+interface AccountResponse {
+  readonly email?: string;
+  readonly locale?: string;
+  readonly subscription?: {
+    readonly isActive?: boolean;
+    readonly plan?: string;
+  };
+  readonly usage?: {
+    readonly percent?: number;
+    readonly remaining?: number;
+  };
+  readonly xUsername?: string;
+}
+
+function isAccountResponse(value: unknown): value is AccountResponse {
+  return typeof value === 'object' && value !== null;
+}
+
+function formatSubscriptionLine(subscription: AccountResponse['subscription']): string {
+  if (subscription === undefined) {
+    return '';
+  }
+  const status = subscription.isActive === true ? 'Active' : 'Inactive';
+  const planSuffix = subscription.plan === undefined ? '' : ` (${subscription.plan})`;
+  return `Subscription: ${status}${planSuffix}`;
+}
+
+function formatUsageLines(usage: AccountResponse['usage']): readonly string[] {
+  if (usage === undefined) {
+    return [];
+  }
+  const lines: string[] = [];
+  if (usage.percent !== undefined) {
+    lines.push(`Usage: ${String(usage.percent)}%`);
+  }
+  if (usage.remaining !== undefined) {
+    lines.push(`Remaining: ${String(usage.remaining)}`);
+  }
+  return lines;
+}
+
+function formatAccountStatus(account: AccountResponse): string {
+  const lines: string[] = [];
+  lines.push('--- Xquik Account Status ---');
+
+  if (account.xUsername !== undefined) {
+    lines.push(`X Account: @${account.xUsername}`);
+  }
+  if (account.email !== undefined) {
+    lines.push(`Email: ${account.email}`);
+  }
+  if (account.locale !== undefined) {
+    lines.push(`Locale: ${account.locale}`);
+  }
+
+  const subscriptionLine = formatSubscriptionLine(account.subscription);
+  if (subscriptionLine.length > 0) {
+    lines.push(subscriptionLine);
+  }
+
+  lines.push(...formatUsageLines(account.usage));
+
+  return lines.join('\n');
+}
+
+async function handleXStatus(request: RequestFunction): Promise<string> {
+  const result: unknown = await request('/api/v1/account');
+  if (!isAccountResponse(result)) {
+    return '--- Xquik Account Status ---';
+  }
+  return formatAccountStatus(result);
+}
+
+export { formatAccountStatus, handleXStatus };

package/src/commands/xtrends.ts

@@ -0,0 +1,59 @@
+import type { RequestFunction } from '../types.js';
+
+interface TrendItem {
+  readonly category?: string;
+  readonly publishedAt?: string;
+  readonly score?: number;
+  readonly source?: string;
+  readonly title: string;
+  readonly url?: string;
+}
+
+interface RadarResponse {
+  readonly items: readonly TrendItem[];
+  readonly total: number;
+}
+
+function isRadarResponse(value: unknown): value is RadarResponse {
+  return typeof value === 'object' && value !== null && 'items' in value && 'total' in value;
+}
+
+function formatTrends(radar: RadarResponse): string {
+  const lines: string[] = [];
+  lines.push(`--- Trending Topics (${String(radar.total)} items) ---`);
+
+  for (const [index, item] of radar.items.entries()) {
+    const position = String(index + 1);
+    let line = `${position}. ${item.title}`;
+    if (item.source !== undefined) {
+      line += ` [${item.source}]`;
+    }
+    if (item.score !== undefined) {
+      line += ` (score: ${String(item.score)})`;
+    }
+    if (item.url !== undefined) {
+      line += `\n   ${item.url}`;
+    }
+    lines.push(line);
+  }
+
+  return lines.join('\n');
+}
+
+async function handleXTrends(request: RequestFunction, categoryFilter?: string): Promise<string> {
+  const query: Record<string, string> = {};
+  if (categoryFilter !== undefined && categoryFilter.length > 0) {
+    const trimmed = categoryFilter.trim();
+    if (trimmed.length > 0) {
+      query.category = trimmed;
+    }
+  }
+  const hasQuery = Object.keys(query).length > 0;
+  const result: unknown = await request('/api/v1/radar', hasQuery ? { query } : undefined);
+  if (!isRadarResponse(result)) {
+    return '--- Trending Topics (0 items) ---';
+  }
+  return formatTrends(result);
+}
+
+export { formatTrends, handleXTrends };

package/src/index.ts

@@ -0,0 +1,153 @@
+import { handleXStatus } from './commands/xstatus.js';
+import { handleXTrends } from './commands/xtrends.js';
+import { createProxiedRequest } from './request.js';
+import { createEventPoller } from './services/event-poller.js';
+import { handleExplore, SEARCH_DESCRIPTION } from './tools/explore.js';
+import { EXECUTE_DESCRIPTION, handleTweetclaw } from './tools/tweetclaw.js';
+import type { FetchFunction, PluginConfig } from './types.js';
+
+interface PollerEvent {
+  readonly eventType?: string;
+  readonly xUsername?: string;
+}
+
+function isPollerEvent(value: unknown): value is PollerEvent {
+  return typeof value === 'object' && value !== null;
+}
+
+const DEFAULT_POLLING_INTERVAL_SECONDS = 60;
+
+interface CommandContext {
+  readonly args?: string;
+}
+
+interface OpenClawApi {
+  readonly config: {
+    readonly plugins?: {
+      readonly entries?: {
+        readonly tweetclaw?: {
+          readonly config?: PluginConfig;
+        };
+      };
+    };
+  };
+  readonly logger: {
+    readonly info: (message: string) => void;
+    readonly warn: (message: string) => void;
+  };
+  readonly registerCommand: (options: {
+    readonly acceptsArguments?: 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;
+  }) => void;
+  readonly registerTool: (
+    options: {
+      readonly description: string;
+      readonly name: string;
+      readonly parameters: {
+        readonly properties: Readonly<Record<string, { readonly description: string; readonly type: string }>>;
+        readonly required: readonly string[];
+        readonly type: string;
+      };
+    },
+    handler: (params: { readonly code: string }) => Promise<{
+      readonly content: ReadonlyArray<{ readonly text: string; readonly type: string }>;
+      readonly isError?: true;
+    }>,
+  ) => void;
+  readonly sendMessage: (text: string) => void;
+}
+
+const CODE_PARAMETER = {
+  properties: {
+    code: { description: 'Async arrow function to execute', type: 'string' },
+  },
+  required: ['code'] as const,
+  type: 'object',
+};
+
+export default function register(api: OpenClawApi, fetchFunction?: FetchFunction): void {
+  const config = api.config.plugins?.entries?.tweetclaw?.config;
+  if (config?.apiKey === undefined) {
+    api.logger.warn(
+      "TweetClaw: No API key configured. Run: openclaw config set plugins.entries.tweetclaw.config.apiKey 'xq_YOUR_KEY'",
+    );
+    return;
+  }
+
+  const { apiKey, baseUrl = 'https://xquik.com' } = config;
+  const request = createProxiedRequest(baseUrl, apiKey, fetchFunction);
+
+  // --- Tools (Cloudflare Code Mode pattern) ---
+  api.registerTool(
+    {
+      description: SEARCH_DESCRIPTION,
+      name: 'explore',
+      parameters: CODE_PARAMETER,
+    },
+    async ({ code }) => handleExplore(code),
+  );
+
+  api.registerTool(
+    {
+      description: EXECUTE_DESCRIPTION,
+      name: 'tweetclaw',
+      parameters: CODE_PARAMETER,
+    },
+    async ({ code }) => handleTweetclaw({ apiKey, baseUrl, code, fetchFunction }),
+  );
+
+  // --- Commands (instant, no LLM) ---
+  api.registerCommand({
+    description: 'Show Xquik account status & usage',
+    handler: async () => {
+      const text = await handleXStatus(request);
+      return { text };
+    },
+    name: 'xstatus',
+  });
+
+  api.registerCommand({
+    acceptsArguments: true,
+    description: 'Show trending topics on X',
+    handler: async ({ args }) => {
+      const text = await handleXTrends(request, args);
+      return { text };
+    },
+    name: 'xtrends',
+  });
+
+  // --- Background event poller ---
+  const { pollingEnabled, pollingInterval } = config;
+  if (pollingEnabled !== false) {
+    const poller = createEventPoller({
+      intervalSeconds: pollingInterval ?? DEFAULT_POLLING_INTERVAL_SECONDS,
+      onEvents: (events) => {
+        for (const event of events) {
+          const eventType: string = isPollerEvent(event) && typeof event.eventType === 'string'
+            ? event.eventType
+            : 'unknown';
+          const username: string = isPollerEvent(event) && typeof event.xUsername === 'string'
+            ? event.xUsername
+            : '';
+          api.sendMessage(`[TweetClaw] ${eventType} from @${username}`);
+        }
+      },
+      request,
+    });
+
+    api.registerService({
+      id: 'tweetclaw-poller',
+      start: () => { poller.start(); },
+      stop: () => { poller.stop(); },
+    });
+  }
+
+  api.logger.info('TweetClaw: Plugin registered successfully');
+}

package/src/request.ts

@@ -0,0 +1,62 @@
+import type { FetchFunction, RequestFunction, RequestOptions } from './types.js';
+
+const FETCH_TIMEOUT_MS = 30_000;
+const CONTENT_TYPE_HEADER = 'content-type';
+const API_KEY_HEADER = 'x-api-key';
+const AUTHORIZATION_HEADER = 'authorization';
+const BEARER_PREFIX = 'Bearer ';
+const API_KEY_PREFIX = 'xq_';
+const API_V1_PREFIX = '/api/v1/';
+
+function buildAuthHeader(credential: string): Record<string, string> {
+  if (credential.startsWith(API_KEY_PREFIX)) {
+    return { [API_KEY_HEADER]: credential };
+  }
+  return { [AUTHORIZATION_HEADER]: `${BEARER_PREFIX}${credential}` };
+}
+
+function buildFetchHeaders(credential: string, hasBody: boolean): Record<string, string> {
+  const auth = buildAuthHeader(credential);
+  if (hasBody) {
+    return { ...auth, [CONTENT_TYPE_HEADER]: 'application/json' };
+  }
+  return auth;
+}
+
+function buildFetchUrl(baseUrl: string, path: string, query?: Readonly<Record<string, string>>): string {
+  const url = new URL(path, baseUrl);
+  if (query !== undefined) {
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+}
+
+function createProxiedRequest(
+  baseUrl: string,
+  apiKey: string,
+  fetchFunction: FetchFunction = fetch,
+): RequestFunction {
+  return async (path: string, options?: Readonly<RequestOptions>): Promise<unknown> => {
+    if (!path.startsWith(API_V1_PREFIX)) {
+      throw new Error(`Path must start with /api/v1/ but got: ${path}`);
+    }
+    const hasBody = options?.body !== undefined;
+    const response = await fetchFunction(buildFetchUrl(baseUrl, path, options?.query), {
+      ...(hasBody ? { body: JSON.stringify(options.body) } : {}),
+      headers: buildFetchHeaders(apiKey, hasBody),
+      method: options?.method ?? 'GET',
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    const json: unknown = await response.json();
+    if (!response.ok) {
+      throw new Error(
+        `API request failed: ${String(response.status)} ${response.statusText} - ${JSON.stringify(json)}`,
+      );
+    }
+    return json;
+  };
+}
+
+export { buildAuthHeader, buildFetchHeaders, buildFetchUrl, createProxiedRequest };

package/src/services/event-poller.ts

@@ -0,0 +1,97 @@
+import type { EventPollerOptions } from '../types.js';
+
+const MAX_BACKOFF_SECONDS = 300;
+const BACKOFF_BASE = 2;
+const MS_PER_SECOND = 1000;
+
+interface EventsResponse {
+  readonly events: ReadonlyArray<Record<string, unknown>>;
+  readonly hasMore?: boolean;
+  readonly nextCursor?: string;
+}
+
+function isEventsResponse(value: unknown): value is EventsResponse {
+  return typeof value === 'object' && value !== null && 'events' in value;
+}
+
+interface EventPollerHandle {
+  readonly start: () => void;
+  readonly stop: () => void;
+}
+
+function extractCursor(events: ReadonlyArray<Readonly<Record<string, unknown>>>): string | undefined {
+  const lastEvent = events.at(-1);
+  return typeof lastEvent?.id === 'string' ? lastEvent.id : undefined;
+}
+
+function createEventPoller(options: EventPollerOptions): EventPollerHandle {
+  let timer: ReturnType<typeof setTimeout> | undefined = undefined;
+  let cursor: string | undefined = undefined;
+  let consecutiveErrors = 0;
+  let stopped = false;
+
+  async function poll(): Promise<void> {
+    try {
+      const query: Record<string, string> = {};
+      if (cursor !== undefined) {
+        query.after = cursor;
+      }
+      const hasQuery = Object.keys(query).length > 0;
+      const result: unknown = await options.request(
+        '/api/v1/events',
+        hasQuery ? { query } : undefined,
+      );
+
+      if (!isEventsResponse(result)) {
+        return;
+      }
+
+      if (result.events.length > 0) {
+        options.onEvents(result.events);
+        const newCursor = extractCursor(result.events);
+        if (newCursor !== undefined) {
+          cursor = newCursor;
+        }
+      }
+
+      consecutiveErrors = 0;
+    } catch {
+      consecutiveErrors += 1;
+    }
+  }
+
+  function getNextInterval(): number {
+    if (consecutiveErrors === 0) {
+      return options.intervalSeconds * MS_PER_SECOND;
+    }
+    const backoffSeconds = Math.min(
+      Math.pow(BACKOFF_BASE, consecutiveErrors) * options.intervalSeconds,
+      MAX_BACKOFF_SECONDS,
+    );
+    return backoffSeconds * MS_PER_SECOND;
+  }
+
+  async function loop(): Promise<void> {
+    await poll();
+    if (stopped) {
+      return;
+    }
+    timer = setTimeout(() => { void loop(); }, getNextInterval());
+  }
+
+  return {
+    start(): void {
+      stopped = false;
+      timer = setTimeout(() => { void loop(); }, options.intervalSeconds * MS_PER_SECOND);
+    },
+    stop(): void {
+      stopped = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+    },
+  };
+}
+
+export { createEventPoller };

package/src/tools/explore.ts

@@ -0,0 +1,59 @@
+import { API_SPEC } from '../api-spec.js';
+import { AsyncFunction, errorResult, specEndpoints, successResult } from './sandbox.js';
+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.
+
+Write an async arrow function. The sandbox provides:
+
+\`\`\`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'));
+}
+\`\`\``;
+
+async function handleExplore(code: string): Promise<ToolResult> {
+  try {
+    const executor = new AsyncFunction('spec', `return (${code})()`);
+    const result: unknown = await executor({ endpoints: specEndpoints });
+    return successResult(result);
+  } catch (error: unknown) {
+    return errorResult(error);
+  }
+}
+
+export { handleExplore, SEARCH_DESCRIPTION };
+export type { EndpointInfo };

package/src/tools/sandbox.ts

@@ -0,0 +1,58 @@
+import { API_SPEC } from '../api-spec.js';
+import { truncateResponse } from '../truncate.js';
+import type { ToolResult } from '../types.js';
+
+const specEndpoints: ReadonlyArray<Readonly<Record<string, unknown>>> = API_SPEC.map(
+  (endpoint): Readonly<Record<string, unknown>> => ({ ...endpoint }),
+);
+
+function extractErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.constructor.name}: ${error.message}`;
+  }
+  return String(error);
+}
+
+function isAsyncFunctionConstructor(
+  value: unknown,
+): value is new (...parameters: readonly string[]) => (...parameters: readonly unknown[]) => Promise<unknown> {
+  return typeof value === 'function';
+}
+
+function getConstructorFromPrototype(proto: unknown): unknown {
+  if (typeof proto !== 'object' || proto === null) {
+    return undefined;
+  }
+  return 'constructor' in proto ? proto.constructor : undefined;
+}
+
+function resolveAsyncFunctionConstructor(prototype?: unknown): new (
+  ...parameters: readonly string[]
+) => (...parameters: readonly unknown[]) => Promise<unknown> {
+  const asyncPrototype: unknown = prototype ?? Object.getPrototypeOf(async (): Promise<void> => {});
+  const candidate: unknown = getConstructorFromPrototype(asyncPrototype);
+  if (!isAsyncFunctionConstructor(candidate)) {
+    throw new Error('AsyncFunction constructor not found');
+  }
+  return candidate;
+}
+
+const AsyncFunction = resolveAsyncFunctionConstructor();
+
+function successResult(content: unknown): ToolResult {
+  return { content: [{ text: truncateResponse(content), type: 'text' as const }] };
+}
+
+function errorResult(error: unknown): ToolResult {
+  return { content: [{ text: extractErrorMessage(error), type: 'text' as const }], isError: true };
+}
+
+export {
+  AsyncFunction,
+  errorResult,
+  extractErrorMessage,
+  getConstructorFromPrototype,
+  resolveAsyncFunctionConstructor,
+  specEndpoints,
+  successResult,
+};