Twitter API tweet type definition

tweet.ts

/// `id` fields are purposely omitted as they not safe to use in JavaScript.
/// Twitter uses 64 bit ids and JavaScript can only safely represent 2^53-1.

/// I decided to go with `<field>?: type` instead of `<field>: type | null`
/// because of the following line in the api documentation:
///
/// “It is generally safe to consider a nulled field, an empty set, and the
/// absence of a field as the same thing”

/// https://dev.twitter.com/overview/api/tweets

interface Tweet {
    contributors?: TweetUser[]; // deprecated
    coordinates?: TweetPointCoordinates;
    created_at: string;
    current_user_retweet?: TweetTruncatedUser;
    entities: TweetEntities;
    extended_entities: { media: TweetEntitiesMedia; };
    favorite_count?: number;
    favorited?: boolean;
    filter_level?: "none" | "low" | "medium"; // for streaming endpoints
    geo?: TweetPointCoordinates; // deprecated
    id_str: string;
    in_reply_to_screen_name?: string;
    in_reply_to_status_id_str?: string;
    in_reply_to_user_id_str?: string;
    lang: string;
    place?: TweetPlace;
    possibly_sensitive: boolean;
    quoted_status_id_str: string;
    quoted_status: Tweet;
    scopes?: { [key: string]: any };
    retweet_count: number;
    retweeted: boolean;
    retweeted_status?: Tweet;
    source: string;
    text: string;
    truncated: boolean;
    user: TweetTruncatedUser | TweetUser;
    withheld_copyright?: boolean;
    withheld_in_countries?: string[];
    withheld_scope?: string;
}

interface TweetEntities {
    hashtags: TweetHashtag[];
    media: TweetEntitiesMedia[];
    symbols: TweetSymbol[];
    urls: TweetUrl[];
    user_mentions: TweetEntitiesMentions[];
}

interface TweetHashtag {
    text: string;
    indices: [number, number];
}

interface TweetSymbol {
    text: string;
    indices: [number, number];
}

interface TweetPlace {
    attributes: TweetPlaceAttributes;
    bounding_box: TweetPolygonCoordinates;
    contained_within?: TweetPlace[]; // undocumented
    country: string;
    country_code: string;
    full_name: string;
    id: string;
    name: string;
    place_type: string;
    url: string;
}

interface TweetPlaceAttributes {
    [key: string]: string | undefined;
    "app:id"?: string;
    iso3?: string;
    locality?: string;
    phone?: string;
    postal_code?: string;
    region?: string;
    street_address?: string;
    twitter?: string;
    url?: string;
}

interface TweetUrl {
    display_url: string;
    expanded_url: string;
    indices: [number, number];
    url: string;
}

interface TweetUser {
    contributors_enabled: false; // legacy
    created_at: string;
    default_profile: boolean;
    default_profile_image: boolean;
    description?: string;
    entities: TweetUserEntities;
    favourites_count: number;
    follow_request_sent?: boolean;
    followers_count: number;
    following?: boolean; // deprecated
    friends_count: number;
    geo_enabled: false;
    has_extended_profile: boolean;
    id_str: string;
    is_translation_enabled?: boolean;
    is_translator: boolean;
    lang: string;
    listed_count: number;
    location: string;
    name: string;
    notifications: boolean;
    profile_background_color: string;
    profile_background_image_url: string;
    profile_background_image_url_https: string;
    profile_background_tile: string;
    profile_banner_url: string;
    profile_image_url: string;
    profile_image_url_https: string;
    profile_link_color: string;
    profile_sidebar_border_color: string;
    profile_sidebar_fill_color?: string;
    profile_text_color: string;
    profile_use_background_image: boolean;
    protected: boolean;
    screen_name: string;
    status?: Tweet;
    statuses_count: number;
    time_zone: string;
    translator_type?: string;
    url?: string;
    utc_offset: number;
    verified: false;
    withheld_in_countries?: string;
    withheld_scope?: string;
}

interface TweetUserEntities {
    description: {
        urls: TweetUrl[];
    };
    url?: {
        urls: TweetUrl[];
    };
}

interface TweetTruncatedUser {
    id_str: string;
}

interface TweetPointCoordinates {
    coordinates: [number, number];
    type: "Point";
}

interface TweetPolygonCoordinates {
    coordinates: Array<Array<[number, number]>>;
    type: "Polygon";
}

interface TweetEntitiesMentions {
    id_str: string;
    indices: [number, number];
    name: string;
    screen_name: string;
}

interface TweetEntitiesMedia {
    additional_media_info?: TweetAdditionalMediaInfo; // undocumented
    display_url: string;
    expanded_url: string;
    features?: any;
    id_str: string;
    indices: [number, number];
    media_url: string;
    media_url_https: string;
    sizes: TweetEntitiesMediaSizes;
    source_status_id_str: string;
    source_user_id_str: string;
    type: "photo" | "video" | "animated_gif";
    url: string;
    video_info?: TweetVideoInfo;
}

interface TweetEntitiesMediaSizes {
    large: TweetMediaSizeData;
    medium: TweetMediaSizeData;
    small: TweetMediaSizeData;
    thumb: TweetMediaSizeData;
}

interface TweetAdditionalMediaInfo {
    monetizable: boolean;
    source_user: TweetUser;
}

interface TweetVideoInfo {
    aspect_ratio: [number, number];
    duration_millis: number;
    variants: TweetVideoInfoVariants[];
}

interface TweetVideoInfoVariants {
    bitrate?: number;
    content_type: string;
    url: string;
}

interface TweetMediaSizeData {
    h: number;
    resize: "fit" | "crop";
    w: number;
}

export {
    Tweet,
    TweetAdditionalMediaInfo,
    TweetEntities,
    TweetEntitiesMedia,
    TweetEntitiesMediaSizes,
    TweetEntitiesMentions,
    TweetHashtag,
    TweetMediaSizeData,
    TweetPlace,
    TweetPlaceAttributes,
    TweetPointCoordinates,
    TweetPolygonCoordinates,
    TweetSymbol,
    TweetTruncatedUser,
    TweetUrl,
    TweetUser,
    TweetUserEntities,
    TweetVideoInfo,
    TweetVideoInfoVariants,
};

twitter.d.ts

// first stab at type definition for https://github.com/desmondmorris/node-twitter

import { EventEmitter } from "events";
import { ServerResponse } from "http";

interface TwitterClientOptions {
    consumer_key: string;
    consumer_secret: string;
    [opt: string]: any;
}

interface TwitterClientOptionsUser extends TwitterClientOptions {
    access_token_key: string;
    access_token_secret: string;
}

interface TwitterClientOptionsApp extends TwitterClientOptions {
    bearer_token: string;
}

interface TwitterStream extends EventEmitter {
    emit(event: string | symbol, ...args: any[]): boolean;
    emit(event: "data" | "friends" | "event", obj: object): boolean;
    emit(event: "ping"): boolean;

    addListener(event: string | symbol, listener: Function): this;
    addListener(event: "data" | "friends" | "event", listener: (obj: object) => void): this;
    addListener(event: "ping", listener: () => void): this;

    on(event: string | symbol, listener: Function): this;
    on(event: "data" | "friends" | "event", listener: (obj: object) => void): this;
    on(event: "ping", listener: () => void): this;

    once(event: string | symbol, listener: Function): this;
    once(event: "data" | "friends" | "event", listener: (obj: object) => void): this;
    once(event: "ping", listener: () => void): this;

    prependListener(event: string | symbol, listener: Function): this;
    prependListener(event: "data" | "friends" | "event", listener: (obj: object) => void): this;
    prependListener(event: "ping", listener: () => void): this;

    prependOnceListener(event: string | symbol, listener: Function): this;
    prependOnceListener(event: "data" | "friends" | "event", listener: (obj: object) => void): this;
    prependOnceListener(event: "ping", listener: () => void): this;

    removeListener(event: string | symbol, listener: Function): this;
    removeListener(event: "data" | "friends" | "event", listener: (obj: object) => void): this;
    removeListener(event: "ping", listener: () => void): this;
}

type StreamCallback = (stream: TwitterStream) => void;
type RequestCallback = (error: Error, response: ServerResponse, data: object) => void;

interface Params {
    [param: string]: any;
}

declare class Twitter {
    constructor(options: TwitterClientOptionsUser | TwitterClientOptionsApp);
    public get(
        path: string,
        params?: Params | RequestCallback,
        callback?: RequestCallback,
    ): Promise<any>;

    public post(
        path: string,
        params: Params | RequestCallback,
        callback?: RequestCallback,
    ): Promise<any>;

    public stream(
        path: string,
        params: Params | StreamCallback,
        callback?: StreamCallback,
    ): TwitterStream;
}

export = Twitter;

FTFY:

Thanks! I'll likely use these in my functional Twitter API client.