x-developer

# Xquik TypeScript Type Definitions Copy-pasteable TypeScript types for all Xquik API objects. ## Contents - [Account](#account) - [API Keys](#api-keys) - [Credits](#credits) - [Monitors](#monitors) - [Events](#events) - [Webhooks](#webhooks) - [Draws](#draws) - [Extractions](#extractions) - [X API](#x-api) - [Trends](#trends) - [Support](#support) - [Error](#error) - [Request Bodies](#request-bodies) - [MCP Output Schemas](#mcp-output-schemas) ```typescript // ─── Account ───────────────────────────────────────────── interface Account { plan: "active" | "inactive"; monitorsAllowed: number; monitorsUsed: number; monitorBilling: { activeDailyEstimate: string; activeHourlyBurn: string; creditsPerActiveMonitorDay: string; creditsPerActiveMonitorHour: string; eventsIncluded: boolean; instantCheckIntervalSeconds: number; unlimitedSlots: boolean; }; creditInfo?: { balance: string; lifetimePurchased: string; lifetimeUsed: string; autoTopupEnabled: boolean; autoTopupAmountDollars: number; autoTopupThreshold: string; }; xUsername?: string; } // ─── Credits ──────────────────────────────────────────── interface CreditBalance { balance: string; // Current credit balance, bigint string lifetimePurchased: string; // Total credits purchased, bigint string lifetimeUsed: string; // Total credits consumed, bigint string autoTopupEnabled: boolean; // Whether auto top-up is enabled autoTopupAmountDollars: number; // Dollar amount charged by auto top-up autoTopupThreshold: string; // Trigger threshold, bigint string } interface CreditTopUpResponse { url: string; // Checkout URL } type CreditQuickTopUpResponse = | { outcome: "charged"; credits: string; // Credits added, bigint string balance: string; // New balance, bigint string } | { outcome: "no_payment_method" } | { outcome: "requires_action"; clientSecret: string; // Complete required cardholder action }; // ─── API Keys ──────────────────────────────────────────── interface ApiKeyCreated { id: string; fullKey: string; prefix: string; name: string; createdAt: string; } interface ApiKey { id: string; name: string; prefix: string; isActive: boolean; createdAt: string; lastUsedAt?: string; } // ─── Monitors ──────────────────────────────────────────── interface Monitor { id: string; username: string; xUserId: string; eventTypes: EventType[]; isActive: boolean; createdAt: string; } type EventType = | "tweet.new" | "tweet.quote" | "tweet.reply" | "tweet.retweet"; // ─── Events ────────────────────────────────────────────── interface Event { id: string; type: EventType; monitorId: string; username: string; occurredAt: string; data: EventData; xEventId?: string; } // Tweet events (tweet.new, tweet.reply, tweet.quote, tweet.retweet) interface TweetEventData { tweetId: string; text: string; metrics: { likes: number; retweets: number; replies: number; }; // tweet.quote only quotedTweetId?: string; quotedUsername?: string; // tweet.reply only inReplyToTweetId?: string; inReplyToUsername?: string; // tweet.retweet only retweetedTweetId?: string; retweetedUsername?: string; } type EventData = TweetEventData; interface EventList { events: Event[]; hasMore: boolean; nextCursor?: string; } // ─── Webhooks ──────────────────────────────────────────── interface WebhookCreated { id: string; url: string; eventTypes: EventType[]; secret: string; createdAt: string; } interface Webhook { id: string; url: string; eventTypes: EventType[]; isActive: boolean; createdAt: string; } interface Delivery { id: string; streamEventId: string; status: "pending" | "delivered" | "failed" | "exhausted"; attempts: number; lastStatusCode?: number; lastError?: string; createdAt: string; deliveredAt?: string; } interface WebhookPayload { eventType: EventType; username: string; data: EventData; } // ─── Draws ─────────────────────────────────────────────── interface Draw { id: string; tweetId: string; tweetUrl: string; tweetText: string; tweetAuthorUsername: string; tweetLikeCount: number; tweetRetweetCount: number; tweetReplyCount: number; tweetQuoteCount: number; status: "pending" | "running" | "completed" | "failed"; totalEntries: number; validEntries: number; createdAt: string; drawnAt?: string; } interface DrawListItem { id: string; tweetUrl: string; status: "pending" | "running" | "completed" | "failed"; totalEntries: number; validEntries: number; createdAt: string; drawnAt?: string; } interface DrawWinner { position: number; authorUsername: string; tweetId: string; isBackup: boolean; } interface DrawList { draws: DrawListItem[]; hasMore: boolean; nextCursor?: string; } interface CreateDrawRequest { tweetUrl: string; winnerCount?: number; backupCount?: number; uniqueAuthorsOnly?: boolean; mustRetweet?: boolean; mustFollowUsername?: string; filterMinFollowers?: number; filterAccountAgeDays?: number; filterLanguage?: string; requiredKeywords?: string[]; requiredHashtags?: string[]; requiredMentions?: string[]; } // ─── Extractions ───────────────────────────────────────── type ExtractionToolType = | "article_extractor" | "community_extractor" | "community_moderator_explorer" | "community_post_extractor" | "community_search" | "favoriters" | "follower_explorer" | "following_explorer" | "list_follower_explorer" | "list_member_extractor" | "list_post_extractor" | "mention_extractor" | "people_search" | "post_extractor" | "quote_extractor" | "reply_extractor" | "repost_extractor" | "space_explorer" | "thread_extractor" | "tweet_search_extractor" | "user_likes" | "user_media" | "verified_follower_explorer"; interface ExtractionJob { id: string; toolType: ExtractionToolType; status: "pending" | "running" | "completed" | "failed"; totalResults: number; targetTweetId?: string; targetUsername?: string; targetUserId?: string; targetCommunityId?: string; targetListId?: string; targetSpaceId?: string; searchQuery?: string; resultsLimit?: number; // Max results to extract. Stops early instead of fetching all. Omit for all. errorMessage?: string; createdAt: string; completedAt?: string; } interface ExtractionResult { id: string; xUserId: string; xUsername?: string; xDisplayName?: string; xFollowersCount?: number; xVerified?: boolean; xProfileImageUrl?: string; tweetId?: string; tweetText?: string; tweetCreatedAt?: string; createdAt: string; } interface ExtractionList { extractions: ExtractionJob[]; hasMore: boolean; nextCursor?: string; } interface ExtractionEstimate { allowed: boolean; creditsAvailable: string; creditsRequired: string; source: "replyCount" | "retweetCount" | "quoteCount" | "followers" | "unknown"; estimatedResults: number; resolvedXUserId?: string; error?: string; } interface CreateExtractionRequest { toolType: ExtractionToolType; targetTweetId?: string; targetUsername?: string; targetCommunityId?: string; targetListId?: string; targetSpaceId?: string; searchQuery?: string; resultsLimit?: number; // Max results to extract. Stops early instead of fetching all. Omit for all. // Tweet search filters (tweet_search_extractor only) fromUser?: string; toUser?: string; mentioning?: string; language?: string; sinceDate?: string; // YYYY-MM-DD untilDate?: string; // YYYY-MM-DD mediaType?: 'images' | 'videos' | 'gifs' | 'media'; minFaves?: number; minRetweets?: number; minReplies?: number; verifiedOnly?: boolean; replies?: 'include' | 'exclude' | 'only'; retweets?: 'include' | 'exclude' | 'only'; exactPhrase?: string; excludeWords?: string; advancedQuery?: string; } // ─── X API ─────────────────────────────────────────────── interface TweetMediaItem { mediaUrl: string; type: string; // "photo" | "video" | "animated_gif" url: string; } interface Tweet { id: string; text: string; createdAt?: string; retweetCount: number; replyCount: number; likeCount: number; quoteCount: number; viewCount: number; bookmarkCount: number; media?: TweetMediaItem[]; } interface TweetAuthor { id: string; username: string; followers: number; verified: boolean; profilePicture?: string; } interface TweetSearchResult { id: string; text: string; createdAt: string; likeCount: number; // Omitted if unavailable retweetCount: number; // Omitted if unavailable replyCount: number; // Omitted if unavailable media?: TweetMediaItem[]; author: { id: string; username: string; name: string; verified: boolean; }; } interface UserProfile { id: string; username: string; name: string; description?: string; followers?: number; following?: number; verified?: boolean; profilePicture?: string; location?: string; createdAt?: string; statusesCount?: number; } interface FollowerCheck { sourceUsername: string; targetUsername: string; isFollowing: boolean; isFollowedBy: boolean; } // ─── User Activity ────────────────────────────────────── interface UserTweetsResponse { tweets: Tweet[]; hasMore: boolean; nextCursor?: string; } interface UserLikesResponse { tweets: Tweet[]; hasMore: boolean; nextCursor?: string; } interface UserMediaResponse { tweets: Tweet[]; hasMore: boolean; nextCursor?: string; } interface TweetFavoritersResponse { users: UserProfile[]; hasMore: boolean; nextCursor?: string; } interface FollowersYouKnowResponse { users: UserProfile[]; hasMore: boolean; nextCursor?: string; } // ─── Bookmarks & Timeline ─────────────────────────────── interface BookmarksResponse { tweets: Tweet[]; hasMore: boolean; nextCursor?: string; } interface BookmarkFolder { id: string; name: string; } interface BookmarkFoldersResponse { folders: BookmarkFolder[]; } interface NotificationsResponse { notifications: Notification[]; hasMore: boolean; nextCursor?: string; } interface TimelineResponse { tweets: Tweet[]; hasMore: boolean; nextCursor?: string; } interface DmHistoryResponse { messages: DmMessage[]; hasMore: boolean; nextCursor?: string; } interface DmMessage { id: string; text: string; senderId: string; createdAt: string; media?: TweetMediaItem[]; } // ─── X Articles ───────────────────────────────────────── interface Article { title: string; coverImage?: string; bodyHtml: string; likeCount: number; retweetCount: number; replyCount: number; viewCount: number; bookmarkCount: number; author: { id: string; username: string; name: string; }; } // ─── Radar ─────────────────────────────────────────────── type RadarSource = | "github" | "google_trends" | "hacker_news" | "polymarket" | "reddit" | "trustmrr" | "wikipedia"; type RadarCategory = | "general" | "tech" | "dev" | "science" | "culture" | "politics" | "business" | "entertainment"; interface RadarItem { id: string; title: string; description?: string; url?: string; imageUrl?: string; source: RadarSource; sourceId: string; category: RadarCategory; region: string; language: string; score: number; metadata: Record<string, unknown>; publishedAt: string; createdAt: string; } // ─── Download Media ───────────────────────────────────── interface DownloadMediaRequest { tweetInput?: string; // Tweet URL or numeric tweet ID (single mode) tweetIds?: string[]; // Array of tweet URLs or IDs (bulk mode, max 50). Exactly 1 of tweetInput or tweetIds required. } interface DownloadMediaSingleResponse { tweetId: string; // Resolved tweet ID galleryUrl: string; // Shareable gallery page URL cacheHit: boolean; // true if served from cache (no usage consumed) } interface DownloadMediaBulkResponse { galleryUrl: string; // Combined gallery page URL totalTweets: number; // Number of tweets processed totalMedia: number; // Total media items downloaded } // ─── Trends ────────────────────────────────────────────── interface Trend { name: string; description?: string; rank?: number; query?: string; } interface TrendList { trends: Trend[]; total: number; woeid: number; } // ─── Support ──────────────────────────────────────────── interface SupportTicket { id: string; subject: string; status: string; createdAt: string; updatedAt: string; } interface SupportMessage { id: string; body: string; sender: string; createdAt: string; } interface CreateTicketRequest { subject: string; body: string; } // ─── Error ─────────────────────────────────────────────── interface ApiError { error: string; limit?: number; } // ─── Request Bodies ────────────────────────────────────── interface CreateMonitorRequest { username: string; eventTypes: EventType[]; } interface UpdateMonitorRequest { eventTypes?: EventType[]; isActive?: boolean; } interface CreateWebhookRequest { url: string; eventTypes: EventType[]; } interface UpdateWebhookRequest { url?: string; eventTypes?: EventType[]; isActive?: boolean; } interface CreateApiKeyRequest { name?: string; } // --- Tweet Style Cache --- interface TweetStyleCache { xUsername: string; tweetCount: number; isOwnAccount: boolean; fetchedAt: string; // ISO 8601 tweets: CachedTweet[]; } interface CachedTweet { id: string; text: string; authorUsername: string; createdAt: string; // ISO 8601 media?: TweetMediaItem[]; } interface TweetStyleSummary { xUsername: string; tweetCount: number; isOwnAccount: boolean; fetchedAt: string; } interface StyleComparison { style1: TweetStyleCache; style2: TweetStyleCache; } interface StylePerformance { xUsername: string; tweetCount: number; tweets: PerformanceTweet[]; } interface PerformanceTweet { id: string; text: string; likeCount: number; retweetCount: number; replyCount: number; quoteCount: number; viewCount: number; bookmarkCount: number; } // --- Tweet Drafts --- interface TweetDraft { id: string; text: string; topic?: string; goal?: "engagement" | "followers" | "authority" | "conversation"; createdAt: string; // ISO 8601 updatedAt: string; // ISO 8601 } interface TweetDraftList { drafts: TweetDraft[]; afterCursor: string | null; hasMore: boolean; } // --- Account Identity --- interface XIdentityResponse { success: boolean; xUsername: string; } ``` ## REST API vs MCP Field Naming The REST API and MCP server use different field names for the same data. Map these when switching between interfaces: | Type | REST API Field | MCP Field | |------|---------------|-----------| | **Monitor** | `username` | `xUsername` | | **Event** | `type` | `eventType` | | **Event** | `data` | `eventData` | | **Event** | `monitorId` | `monitoredAccountId` | | **UserProfile** | `followers` | `followersCount` | | **UserProfile** | `following` | `followingCount` | | **FollowerCheck** | `isFollowing` / `isFollowedBy` | `following` / `followedBy` | **MCP `get-user-info` returns a subset** of the full `UserProfile` type. Fields not returned by MCP: `verified`, `location`, `createdAt`, `statusesCount`. Use the REST API `GET /x/users/{username}` for the complete profile. ## MCP Output Schemas MCP tools return structured data with these shapes. Field names differ from the REST API (see mapping table above). ```typescript // ─── MCP: get-user-info ───────────────────────────────── interface McpUserInfo { username: string; // X username (without @) name: string; // Display name description: string; // User bio text followersCount: number; // Number of followers followingCount: number; // Number of accounts followed profilePicture: string; // Profile picture URL // Not returned: verified, location, createdAt, statusesCount // Use REST GET /x/users/{username} for the full profile } // ─── MCP: search-tweets ───────────────────────────────── interface McpSearchResult { tweets: { id: string; // Tweet ID (use with lookup-tweet for full metrics) text: string; // Full tweet text authorUsername: string; // X username of the tweet author authorName: string; // Display name of the tweet author createdAt: string; // ISO 8601 timestamp when tweet was posted media?: { mediaUrl: string; type: string; url: string }[]; // Attached photos/videos // No engagement metrics. Use lookup-tweet for those }[]; } // ─── MCP: lookup-tweet ────────────────────────────────── interface McpTweetLookup { tweet: { id: string; // Tweet ID text: string; // Tweet text likeCount: number; // Number of likes retweetCount: number; // Number of retweets replyCount: number; // Number of replies quoteCount: number; // Number of quote tweets viewCount: number; // Number of views bookmarkCount: number; // Number of bookmarks media?: { mediaUrl: string; type: string; url: string }[]; // Attached photos/videos }; author?: { // Tweet author details id: string; // Author user ID username: string; // Author X username followers: number; // Author follower count verified: boolean; // Whether the author is verified }; } // ─── MCP: check-follow ───────────────────────────────── interface McpFollowCheck { following: boolean; // Whether the source follows the target followedBy: boolean; // Whether the target follows the source } // ─── MCP: get-events ──────────────────────────────────── interface McpEventList { events: { id: string; // Event ID (use with get-event for full details) xUsername: string; // Username of the monitored account eventType: string; // Event type (tweet.new, tweet.reply, etc.) eventData: unknown; // Full event payload (tweet text, author, metrics) monitoredAccountId: string; // ID of the monitored account createdAt: string; // ISO 8601 when event was recorded occurredAt: string; // ISO 8601 when event occurred on X }[]; hasMore: boolean; // Whether more results are available nextCursor?: string; // Pass as afterCursor to fetch the next page } // ─── MCP: list-monitors ───────────────────────────────── interface McpMonitorList { monitors: { id: string; // Monitor ID (use with remove-monitor, get-events monitorId filter) xUsername: string; // Monitored X username eventTypes: string[]; // Subscribed event types isActive: boolean; // Whether the monitor is currently active createdAt: string; // ISO 8601 timestamp }[]; } // ─── MCP: add-webhook ─────────────────────────────────── interface McpWebhookCreated { id: string; // Webhook ID url: string; // HTTPS endpoint URL eventTypes: string[]; // Event types delivered to this webhook isActive: boolean; // Whether the webhook is active createdAt: string; // ISO 8601 timestamp secret: string; // HMAC signing secret for verifying webhook payloads. Store securely. } // ─── MCP: test-webhook ────────────────────────────────── interface McpWebhookTest { success: boolean; statusCode: number; error?: string; } // ─── MCP: run-extraction ──────────────────────────────── interface McpExtractionJob { id: string; // Extraction job ID (use with get-extraction for results) toolType: string; // Extraction tool type used status: string; // Job status totalResults: number; // Number of results extracted } // ─── MCP: estimate-extraction ─────────────────────────── interface McpExtractionEstimate { allowed?: boolean; // Whether the extraction is allowed within budget estimatedResults?: number; // Estimated number of results creditsRequired?: string; // Required credits, bigint string creditsAvailable?: string; // Available credits, bigint string source?: string; // Data source used for estimation resolvedXUserId?: string; // Resolved user ID for username-based estimates error?: string; // Error message if estimation failed } // ─── MCP: run-draw ────────────────────────────────────── interface McpDrawResult { id: string; // Draw ID (use with get-draw for full details) tweetId: string; // Giveaway tweet ID totalEntries: number; // Total reply count before filtering validEntries: number; // Valid entries after filtering winners: { position: number; // Winner position (1-based) authorUsername: string; // X username of the winner tweetId: string; // Tweet ID of the winning reply isBackup: boolean; // Whether this is a backup winner }[]; } // ─── MCP: get-draw ────────────────────────────────────── interface McpDrawDetails { draw: { id: string; // Draw ID status: string; // Draw status (completed, failed) createdAt: string; // ISO 8601 timestamp drawnAt?: string; // ISO 8601 timestamp when winners were drawn totalEntries: number; // Total reply count before filtering validEntries: number; // Entries remaining after filters applied tweetId: string; // Giveaway tweet ID tweetUrl: string; // Full URL of the giveaway tweet tweetText: string; // Giveaway tweet text tweetAuthorUsername: string; // Username of the giveaway tweet author tweetLikeCount: number; // Tweet like count at draw time tweetRetweetCount: number; // Tweet retweet count at draw time tweetReplyCount: number; // Tweet reply count at draw time tweetQuoteCount: number; // Tweet quote count at draw time }; winners: { position: number; // Winner position (1-based) authorUsername: string; // X username of the winner tweetId: string; // Tweet ID of the winning reply isBackup: boolean; // Whether this is a backup winner }[]; } // ─── MCP: get-account ─────────────────────────────────── interface McpAccount { plan: "active" | "inactive"; monitorsAllowed: number; // Deprecated; monitor slots are unlimited monitorsUsed: number; // Number of active monitors monitorBilling: { activeDailyEstimate: string; activeHourlyBurn: string; creditsPerActiveMonitorDay: string; creditsPerActiveMonitorHour: string; eventsIncluded: boolean; instantCheckIntervalSeconds: number; unlimitedSlots: boolean; }; creditInfo?: { balance: string; lifetimePurchased: string; lifetimeUsed: string; autoTopupEnabled: boolean; autoTopupAmountDollars: number; autoTopupThreshold: string; }; xUsername?: string; } // ─── MCP: get-trends ──────────────────────────────────── interface McpTrends { woeid: number; total: number; trends: { name: string; // Trend name or hashtag rank?: number; // Trend rank position description?: string; // Trend description or context query?: string; // Search query to find tweets for this trend }[]; } // ─── MCP: subscribe ──────────────────────────────────── interface McpSubscribe { status: "already_subscribed" | "checkout_created" | "payment_issue"; url: string; // Checkout or Customer Portal URL. Open in browser. message: string; // Human-readable status message } // ─── MCP: compose-tweet ──────────────────────────────── interface McpComposeTweet { algorithmInsights: { name: string; // Signal name from PhoenixScores polarity: "positive" | "negative"; // Whether this signal helps or hurts ranking description: string; // What this signal measures }[]; contentRules: { rule: string; // Actionable content rule description: string; // Why this rule matters based on algorithm architecture }[]; engagementMultipliers: { action: string; // Engagement action (e.g. reply chain, quote tweet) multiplier: string; // Relative value compared to a like (e.g. "27x a like") source: string; // Data source for this multiplier }[]; engagementVelocity: string; // How early engagement velocity affects distribution followUpQuestions: string[]; // Questions for the AI to ask the user before composing scorerWeights: { signal: string; // Signal name in the scoring model weight: number; // Weight applied to predicted probability context: string; // Practical meaning of this weight }[]; topPenalties: string[]; // Most severe negative signals to avoid source: string; // Attribution to algorithm source code } // ─── MCP: refine-tweet ───────────────────────────────── interface McpRefineTweet { compositionGuidance: string[]; // Targeted guidance based on user preferences examplePatterns: { pattern: string; // Tweet structure template description: string; // What this pattern achieves }[]; } // ─── MCP: score-tweet ────────────────────────────────── interface McpScoreTweet { totalChecks: number; // Total number of checks performed passedCount: number; // Number of checks that passed topSuggestion: string; // Highest-impact improvement suggestion checklist: { factor: string; // What was checked passed: boolean; // Whether the check passed suggestion?: string; // Improvement suggestion (present only if failed) }[]; } // ─── X Accounts (Connected) ────────────────────────── interface ConnectedXAccount { id: string; // Unique account ID username: string; // X username displayName?: string; // Display name on X isActive: boolean; // Whether the connection is active createdAt: string; // ISO 8601 timestamp } // Connecting an X account is done by the user in the Xquik dashboard, // not through this skill. The skill never handles X login material. // ─── X Write ────────────────────────────────────────── interface CreateTweetRequest { account: string; // Connected X username or account ID text: string; // Tweet text (280 chars, or 25,000 if is_note_tweet) reply_to_tweet_id?: string; // Tweet ID to reply to attachment_url?: string; // URL to attach as card community_id?: string; // Community ID to post into is_note_tweet?: boolean; // Long-form note tweet (up to 25,000 chars) media_ids?: string[]; // Media IDs from POST /x/media (max 4 images or 1 video) } interface CreateTweetResponse { tweetId: string; // ID of the newly created tweet success: boolean; // Always true on success } interface WriteActionRequest { account: string; // Connected X username or account ID } interface SendDmRequest { account: string; // Connected X username or account ID text: string; // Message text media_ids?: string[]; // Media IDs to attach reply_to_message_id?: string; // Message ID to reply to } interface UpdateProfileRequest { account: string; // Connected X username or account ID name?: string; // Display name description?: string; // Bio location?: string; // Location url?: string; // Website URL } ```