TypeScript types for tweets, followers & X API

// ─── Account ─────────────────────────────────────────────

interface Account {
  plan: "active" | "inactive";
  monitorsAllowed: number;
  monitorsUsed: number;
  creditInfo?: {
    balance: number;
    lifetimePurchased: number;
    lifetimeUsed: number;
    autoTopupEnabled: boolean;
  };
  xUsername?: string;
}

// ─── API Keys ────────────────────────────────────────────

// Returned when creating a new key (includes full key)
interface ApiKeyCreated {
  id: string;
  fullKey: string;
  prefix: string;
  name: string;
  createdAt: string;
}

// Returned when listing keys (full key is never exposed)
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;
  nextBillingAt: string;
}

interface KeywordMonitor {
  id: string;
  query: string;
  eventTypes: EventType[];
  isActive: boolean;
  createdAt: string;
  nextBillingAt: string;
}

// ─── Events ──────────────────────────────────────────────

interface Event {
  id: string;
  type: EventType;
  monitorId: string;
  monitorType: "account" | "keyword";
  occurredAt: string;
  data: EventData;
  username?: string;
  query?: string;
  keywordMonitorId?: string;
  xEventId?: string;
}

interface EventList {
  events: Event[];
  hasMore: boolean;
  nextCursor?: string;
}

// ─── Webhooks ────────────────────────────────────────────

// Returned when creating a webhook (includes signing secret)
interface WebhookCreated {
  id: string;
  url: string;
  eventTypes: EventType[];
  secret: string;
  createdAt: string;
}

// Returned when listing webhooks (secret is never exposed)
interface Webhook {
  id: string;
  url: string;
  eventTypes: EventType[];
  isActive: boolean;
  createdAt: string;
}

// ─── Deliveries ──────────────────────────────────────────

interface Delivery {
  id: string;
  streamEventId: string;
  status: "pending" | "delivered" | "failed" | "exhausted";
  attempts: number;
  lastStatusCode?: number;
  lastError?: string;
  createdAt: string;
  deliveredAt?: string;
}

// ─── Webhook Payload ─────────────────────────────────────

interface WebhookPayload {
  eventType: EventType;
  schemaVersion: 1;
  deliveryId: string;
  streamEventId: string;
  occurredAt: string;
  data: EventData;
  username?: string;
  query?: string;
}

interface WebhookTestPayload {
  eventType: "webhook.test";
  data: { message: string };
  timestamp: string;
}

// ─── 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;
}

// ─── Extractions ────────────────────────────────────────

interface ExtractionJob {
  id: string;
  toolType: ExtractionToolType;
  status: "pending" | "running" | "completed" | "failed";
  totalResults: number;
  targetTweetId?: string;
  targetUsername?: string;
  targetUserId?: string;
  targetCommunityId?: string;
  searchQuery?: string;
  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;
  enrichmentData?: Record<string, unknown>;
}

interface ExtractionList {
  extractions: ExtractionJob[];
  hasMore: boolean;
  nextCursor?: string;
}

interface ExtractionEstimate {
  allowed: boolean;
  source: "collection" | "followers" | "following" | "paginationCap" | "quoteCount" | "replyCount" | "resultsLimit" | "retweetCount" | "unknown";
  estimatedResults: number;
  creditsRequired: string;
  creditsAvailable: string;
  resolvedXUserId?: string;
}

// ─── X API ──────────────────────────────────────────────

interface Tweet {
  id: string;
  text: string;
  type?: string;
  createdAt?: string;
  retweetCount?: number;
  replyCount?: number;
  likeCount?: number;
  quoteCount?: number;
  viewCount?: number;
  bookmarkCount?: number;
  media?: TweetMediaItem[];
  url?: string;
  lang?: string;
  isReply?: boolean;
  inReplyToId?: string;
  inReplyToUserId?: string;
  inReplyToUsername?: string;
  conversationId?: string;
  source?: string;
  displayTextRange?: number[];
  textHighlights?: Array<{ startIndex: number; endIndex: number }>;
  isNoteTweet?: boolean;
  isQuoteStatus?: boolean;
  isRetweet?: boolean;
  isLimitedReply?: boolean;
  entities?: Record<string, unknown>;
  author?: UserProfile;
  quoted_tweet?: Tweet;
  retweeted_tweet?: Tweet;
}

interface TweetAuthor {
  id: string;
  username: string;
  followers: number;
  verified: boolean;
  profilePicture?: string;
}

interface TweetSearchResult {
  id: string;
  text: string;
  createdAt: string;
  likeCount: number;
  retweetCount: number;
  replyCount: number;
  author: {
    id: string;
    username: string;
    name: string;
    verified: boolean;
  };
  media?: TweetMediaItem[];
}

interface UserProfile {
  id: string;
  username: string;
  name: string;
  description?: string;
  followers?: number;
  following?: number;
  verified?: boolean;
  profilePicture?: string;
  coverPicture?: string;
  location?: string;
  createdAt?: string;
  statusesCount?: number;
  mediaCount?: number;
  url?: string;
  favouritesCount?: number;
  hasCustomTimelines?: boolean;
  isTranslator?: boolean;
  withheldInCountries?: string[];
  possiblySensitive?: boolean;
  pinnedTweetIds?: string[];
  isAutomated?: boolean;
  automatedBy?: string;
  unavailable?: boolean;
  unavailableReason?: string;
  verifiedType?: string;
  profile_bio?: Record<string, unknown>;
}

interface FollowerCheck {
  sourceUsername: string;
  targetUsername: string;
  isFollowing: boolean;
  isFollowedBy: boolean;
}

// ─── Trends ─────────────────────────────────────────────

interface Trend {
  name: string;
  description?: string;
  rank?: number;
  query?: string;
}

interface TrendList {
  trends: Trend[];
  total: number;
  woeid: number;
}

// ─── Radar ──────────────────────────────────────────────

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;
}

interface RadarList {
  items: RadarItem[];
  hasMore: boolean;
  nextCursor?: string;
}

// ─── Styles ─────────────────────────────────────────────

interface StyleProfile {
  xUsername: string;
  isOwnAccount: boolean;
  tweetCount: number;
  fetchedAt: string;
  tweets: StyleTweet[];
}

interface StyleListItem {
  xUsername: string;
  isOwnAccount: boolean;
  tweetCount: number;
  fetchedAt: string;
}

interface StyleList {
  styles: StyleListItem[];
}

interface StyleComparison {
  style1: StyleProfile;
  style2: StyleProfile;
}

interface PerformanceAnalysis {
  xUsername: string;
  tweetCount: number;
  tweets: PerformanceTweet[];
}

// ─── Drafts ─────────────────────────────────────────────

interface Draft {
  id: string;
  text: string;
  topic?: string;
  goal?: "engagement" | "followers" | "authority" | "conversation";
  createdAt: string;
  updatedAt: string;
}

interface DraftList {
  drafts: Draft[];
  hasMore: boolean;
  nextCursor?: string;
}

// ─── X Accounts ───────────────────────────────────────────

interface XAccount {
  id: string;
  username: string;
  displayName: string;
  isActive: boolean;
  createdAt: string;
}

// ─── Compose ──────────────────────────────────────────────

interface RadarRecommendation {
  endpoint: string;
  guidance: string;
  source: RadarSource;
  useFor: string;
}

// step="compose" response
interface ComposeTweetResult {
  contentRules: { rule: string }[];
  engagementMultipliers: { action: string; multiplier: string }[];
  engagementVelocity: string;
  followUpQuestions: string[];
  intentUrl: string;
  nextStep: string;
  radarRecommendations: RadarRecommendation[];
  savedStyles?: { tweetCount: number; username: string }[];
  scorerWeights: { signal: string; weight: null; context: string }[];
  source: string;
  styleNote?: string;
  styleTweets?: string[];
  topPenalties: string[];
}

// step="refine" response
interface RefineTweetResult {
  compositionGuidance: string[];
  examplePatterns: { description: string; pattern: string }[];
  intentUrl: string;
  nextStep: string;
}

// step="score" response
interface ScoreTweetResult {
  passed: boolean;
  passedCount: number;
  totalChecks: number;
  topSuggestion: string;
  nextStep: string;
  checklist: { factor: string; passed: boolean; suggestion?: string }[];
  intentUrl?: string;
}

// ─── X Write ──────────────────────────────────────────────

interface XWriteResponse {
  success: boolean;
  data?: Record<string, unknown>;
}

// ─── Support Tickets ──────────────────────────────────────

interface SupportTicket {
  publicId: string;
  subject: string;
  status: "open" | "in_progress" | "resolved" | "closed";
  messageCount: number;
  createdAt: string;
  updatedAt: string;
}

interface SupportTicketDetail {
  publicId: string;
  subject: string;
  status: "open" | "in_progress" | "resolved" | "closed";
  createdAt: string;
  updatedAt: string;
  messages: SupportMessage[];
}

interface SupportMessage {
  body: string;
  sender: "user" | "support";
  createdAt: string;
}

// ─── Error Response ──────────────────────────────────────

type ApiErrorType =
  | "api_error"
  | "authentication_error"
  | "billing_error"
  | "dependency_error"
  | "invalid_request_error"
  | "permission_error"
  | "rate_limit_error";

interface StructuredApiError {
  message: string;
  type: ApiErrorType;
  code: string;
}

interface ApiError {
  error: string | StructuredApiError;
  message?: string;
  reason?: string;
  retryAfter?: number;
  retryAfterMs?: number;
}