Data Types

interface Tweet {
    id: string; // X status id. The dedupe key across `tweet` and `tweet_update`
    createdAt: string | number; // ISO string or epoch ms depending on the source. `new Date(createdAt)` handles both
    type: 'TWEET' | 'REPLY' | 'QUOTE' | 'RETWEET';
    author: Author;
    text: string; // Full text with t.co links expanded. Retweets carry the original post's text
    translation: Translation | null; // Set when X provided a translation
    components: Component[] | null; // Rich blocks for long-form posts
    isRetweet: boolean;
    isQuote: boolean;
    isReply: boolean;
    isSelfReply?: boolean; // Reply to the author's own post (thread)
    replyTo: NestedTweet | TweetRef | null; // Replies: the parent post, or just its ref while it resolves
    quotedTweet: NestedTweet | TweetRef | null; // Quotes (and retweets of quotes): the quoted post
    originalAuthor: OriginalAuthor | null; // Retweets: the original author
    media: Media; // Always empty on retweets, see `originalMedia`
    originalMedia: Media | null; // Retweets: the original post's media
    retweetedQuote: NestedTweet | null; // Retweet of a quote: the quoted post
    repliedQuote: NestedTweet | null; // Reply to a quote: the quoted post
    retweetedReplyTo: NestedTweet | null; // Retweet of a reply: the post that was replied to
    card: Card | null;
    article: Article | null;
    grok: GrokChat | null;
    poll: Poll | null;
    metrics: Metrics | null;
    tweetUrl: string; // Link to the post on X
    provider: string; // Which J7 ingest path delivered it (`p_v0`, `p_v1`, ...). Faster paths can carry less data
    isCustomAccount?: boolean; // Delivered because it is one of your custom / available accounts
    retweetTranslation?: Translation; // Retweets: translation of the original post

    // Only on `p_v1` posts, when the upstream detected a contract address:
    contractAddress?: string;
    chain?: string;
    contractAddressLabel?: string;
    preferredTradingUrl?: string;
    extraContractAddresses?: string[]; // Up to 4 more addresses
}

interface Author {
    id: string; // X user id
    handle: string; // Without the @
    name: string;
    avatar: string | null;
    verified: boolean;
    badge: string | null; // X verification badge as reported upstream
    parody: boolean;
    followersCount: number;
    bio?: string;
    location?: string;
    banner?: string;
    website?: string;
    verifiedType?: string;
    affiliateDescription?: string; // Affiliation label shown next to the name
    affiliateBadgeUrl?: string;
    affiliateUrl?: string;
    affiliateLabelType?: string;
}

interface OriginalAuthor {
    id: string;
    handle: string;
    name: string;
    avatar: string | null;
    verified: boolean;
    badge: string | null;
}

interface NestedTweet {
    id: string;
    handle: string; // Author handle
    name: string; // Author name
    avatar: string | null;
    verified: boolean;
    badge: string | null;
    parody: boolean;
    text: string;
    type?: 'TWEET' | 'REPLY' | 'QUOTE' | 'RETWEET';
    createdAt?: string | number;
    media: Media;
    translation: Translation | null;
    card: Card | null;
    article: Article | null;
    grok: GrokChat | null;
    poll: Poll | null;
    metrics?: Metrics | null;
    components?: Component[] | null;
    quotedTweet?: NestedTweet | TweetRef | null;
    replyTo?: NestedTweet | TweetRef | null;
    followersCount?: number;
    tweetLink?: string;
    authorBio?: string;
    authorLocation?: string;
    authorWebsite?: string;
    authorBanner?: string;
}

// Sent in place of a NestedTweet while the referenced post hasn't been resolved yet.
// A later `tweet_update` replaces it with the full NestedTweet.
interface TweetRef {
    id: string;
    handle: string;
}

interface Media {
    images: { url: string; width: number; height: number }[]; // width / height are 0 (not measured)
    videos: { url: string; thumbnail: string; width: number; height: number }[];
}

interface Translation {
    from: string; // Source language
    to: string; // Target language
    text: string;
}

interface Component {
    type: 'text' | 'image' | 'video';
    text?: string;
    url?: string;
}

interface Card {
    url: string;
    image: string | null;
    title: string;
    description: string;
}

interface Article {
    id: string;
    title: string;
    url: string;
    thumbnail: string | null;
    description: string;
    author: string;
    created_at: string;
    updated_at: string;
    body: { text: string; components: Component[] };
}

interface GrokChat {
    id: string;
    conversation: { from: string; message: string; images: string[] }[];
}

interface Poll {
    ends_at: string;
    choices: { label: string; count: number; image: string | null }[];
}

interface Metrics {
    likes: number;
    quotes: number;
    replies: number;
    retweets: number;
    views: number;
}

interface TwitterUser {
    id: string;
    handle: string;
    verified: boolean;
    private: boolean; // Can also appear as `protected`, or under `profile`
    metrics: { followers: number };
    profile: {
        name: string;
        avatar: string;
        banner: string;
        description: string | { text: string }; // Handle both forms
        location: string;
        url: string | { url: string }; // Handle both forms
        badge: string | null;
        parody: boolean;
    };
}

interface RawTweet {
    id: string;
    created_at: string;
    type: string;
    author: { id: string; handle: string; profile: { name: string; avatar: string } };
    body: { text: string };
}

interface SocialPost {
    id: string; // Unique per post. Dedupe key
    createdAt: string; // ISO time
    type: 'EXTERNAL';
    source: 'external';
    platform: 'TRUTH SOCIAL' | 'INSTAGRAM' | 'TIKTOK' | 'YOUTUBE' | 'BINANCE SQUARE';
    author: { handle: string; name: string; avatar: string; verified: boolean };
    text: string; // HTML-entity encoded (& < > "). Decode before display
    media: {
        images: string[]; // Plain URL strings, unlike X
        videos: { url: string; poster?: string }[];
        thumbnails?: string[];
    };
    tweetUrl: string; // Link to the post on its platform
    isRetweet: boolean;
    isQuote: boolean;
    isReply: boolean;
    quotedTweet: object | null; // Platform-specific
    originalAuthor: object | null; // Platform-specific
    replyTo: object | null; // Platform-specific
    card: object | null; // Link preview (Truth Social only)
    timestamp?: number; // Epoch ms. Only on items replayed in `initialTweets`
}