fxtwitter 0.0.0-reserved → 2.0.0

package/dist/v2.d.cts

@@ -0,0 +1,685 @@
+import { t as ClientOptions } from "./http-CidaL0TV.cjs";
+declare namespace v2_d_exports {
+  export { AboutAccount, AnyMedia, AnyReply, AnyStatus, Article, ArticleContent, ArticleContentBlock, ArticleEntity, ArticleImageInfo, ArticleMarkdownEntity, ArticleMediaEntity, ArticleMediaEntityRef, ArticleMediaInfo, ArticleTweetEntity, ArticleVideoInfo, Birthday, Broadcast, BroadcastOrientation, BroadcastState, BroadcastThumbnail, Card, CardImage, Community, CommunityInvitesPolicy, CommunityJoinPolicy, CommunityNote, Cursor, EmbedCard, ExternalMedia, Facet, GenericMedia, GroupedSearchResults, MosaicPhoto, Photo, Poll, PollChoice, ProfileAboutResponse, ProfileRelationshipList, ProfileResponse, QueryError, RawText, ReplyingTo, RepostedBy, SearchResults, SocialConversationResponse, SocialThreadResponse, StatusMedia, StatusRawText, StatusTombstone, Substatus, SubstatusMedia, ThreadTimelineEntry, TimelineEntry, TombstoneReason, Translation, Trend, TrendsResponse, TwitterStatus, TypeaheadEvent, TypeaheadResponse, TypeaheadTopic, User, UserListResults, Verification, VerificationType, Video, VideoCodec, VideoContainer, VideoFormat, Website };
+}
+interface Facet {
+  /** e.g. `url`, `mention`, `hashtag`, `bold`, `media`. */
+  type: string;
+  /** Start/end UTF-16 indices. */
+  indices: [number, number];
+  original?: string;
+  replacement?: string;
+  display?: string;
+  id?: string;
+}
+interface RawText {
+  text: string;
+  facets: Facet[];
+}
+interface StatusRawText extends RawText {
+  display_text_range: [number, number];
+}
+interface Website {
+  url: string;
+  display_url: string;
+}
+interface Birthday {
+  day?: number;
+  month?: number;
+  year?: number;
+}
+type VerificationType = "organization" | "government" | "individual" | null;
+interface Verification {
+  verified: boolean;
+  type: VerificationType;
+  verified_at?: string | null;
+  identity_verified?: boolean;
+  verified_by?: string;
+}
+interface AboutAccount {
+  based_in?: string | null;
+  location_accurate?: boolean;
+  created_country_accurate?: boolean | null;
+  source?: string | null;
+  username_changes?: {
+    count: number;
+    last_changed_at: string | null;
+  };
+}
+interface User {
+  type: "profile";
+  id: string;
+  name: string;
+  screen_name: string;
+  avatar_url: string | null;
+  banner_url: string | null;
+  description: string;
+  raw_description: RawText;
+  location: string;
+  url: string;
+  protected: boolean;
+  followers: number;
+  following: number;
+  statuses: number;
+  media_count: number;
+  likes: number;
+  joined: string;
+  website: Website | null;
+  birthday?: Birthday | null;
+  verification?: Verification;
+  /** Only present when the request opted in via `aboutAccount`. */
+  about_account?: AboutAccount;
+  profile_embed?: boolean;
+}
+interface ReplyingTo {
+  /** Handle or account id used in permalinks. */
+  screen_name: string;
+  /** Parent post id (X snowflake). */
+  status: string;
+  url?: string;
+  profile_url?: string;
+  display_name?: string;
+}
+interface RepostedBy {
+  id: string;
+  name: string;
+  screen_name: string;
+  avatar_url?: string | null;
+  url?: string;
+}
+type VideoContainer = "mp4" | "webm" | "m3u8";
+type VideoCodec = "h264" | "hevc" | "vp9" | "av1";
+interface VideoFormat {
+  container?: VideoContainer;
+  codec?: VideoCodec;
+  bitrate?: number;
+  url: string;
+  size?: number;
+  height?: number;
+  width?: number;
+}
+interface Photo {
+  id?: string;
+  format?: string;
+  type: "photo" | "gif";
+  url: string;
+  width: number;
+  height: number;
+  transcode_url?: string | null;
+  altText?: string;
+}
+interface Video {
+  id?: string;
+  format?: string;
+  type: "video" | "gif";
+  url: string;
+  width: number;
+  height: number;
+  thumbnail_url?: string | null;
+  transcode_url?: string | null;
+  duration: number;
+  filesize?: number;
+  formats: VideoFormat[];
+  publisher?: User | null;
+}
+interface MosaicPhoto {
+  id?: string;
+  format?: string;
+  type: "mosaic_photo";
+  url: string;
+  width: number;
+  height: number;
+  formats: {
+    webp: string;
+    jpeg: string;
+  };
+}
+interface ExternalMedia {
+  /** Currently always `video`. */
+  type: "video";
+  url: string;
+  thumbnail_url?: string;
+  height?: number;
+  width?: number;
+}
+/** Any other media item shape the API may return that isn't one of the known kinds. */
+interface GenericMedia {
+  id?: string;
+  format?: string;
+  type: string;
+  url: string;
+  width: number;
+  height: number;
+}
+type AnyMedia = Photo | Video | MosaicPhoto | GenericMedia;
+type BroadcastState = "LIVE" | "ENDED";
+type BroadcastOrientation = "landscape" | "portrait";
+interface BroadcastThumbnail {
+  url: string;
+}
+interface Broadcast {
+  url: string;
+  width: number;
+  height: number;
+  state: BroadcastState;
+  broadcaster: {
+    username: string;
+    display_name: string;
+    id: string;
+  };
+  stream?: {
+    url: string;
+  };
+  title: string;
+  source: string;
+  orientation: BroadcastOrientation;
+  broadcast_id: string;
+  media_id: string;
+  media_key: string;
+  is_high_latency: boolean;
+  thumbnail: {
+    original: BroadcastThumbnail;
+    small?: BroadcastThumbnail;
+    medium?: BroadcastThumbnail;
+    large?: BroadcastThumbnail;
+    x_large?: BroadcastThumbnail;
+  };
+}
+interface StatusMedia {
+  external?: ExternalMedia;
+  photos?: Photo[];
+  videos?: Video[];
+  /** Preserves original ordering across photos and videos. */
+  all?: AnyMedia[];
+  mosaic?: MosaicPhoto;
+  broadcast?: Broadcast;
+}
+type SubstatusMedia = StatusMedia;
+interface PollChoice {
+  label: string;
+  count: number;
+  percentage: number;
+}
+interface Poll {
+  choices: PollChoice[];
+  total_votes: number;
+  ends_at: string;
+  time_left_en: string;
+}
+interface Translation {
+  text: string;
+  source_lang: string;
+  source_lang_en: string;
+  target_lang: string;
+  provider: string;
+}
+interface CardImage {
+  width?: number;
+  height?: number;
+  url?: string;
+  alt?: string;
+}
+interface Card {
+  url: string;
+  title?: string;
+  description?: string;
+  domain?: string;
+  card_name?: string;
+  image?: CardImage;
+}
+interface CommunityNote {
+  text: string;
+  facets: Facet[];
+}
+type CommunityJoinPolicy = "Open" | "Closed";
+type CommunityInvitesPolicy = "MemberInvitesAllowed" | "MemberInvitesDisabled";
+interface Community {
+  id: string;
+  name: string;
+  description: string;
+  created_at: string;
+  search_tags: string[];
+  is_nsfw: boolean;
+  topic: string | null;
+  admin?: User | null;
+  creator?: User | null;
+  join_policy?: CommunityJoinPolicy;
+  invites_policy?: CommunityInvitesPolicy;
+  is_pinned: boolean;
+}
+interface RgbColor {
+  red: number;
+  green: number;
+  blue: number;
+}
+interface ColorPalette {
+  palette: Array<{
+    percentage: number;
+    rgb: RgbColor;
+  }>;
+}
+interface ArticleImageInfo {
+  __typename: "ApiImage";
+  original_img_height: number;
+  original_img_width: number;
+  original_img_url: string;
+  color_info: ColorPalette;
+}
+interface ArticleVideoInfo {
+  __typename: "ApiVideo" | "ApiGif";
+  type: "video" | "animated_gif";
+  id: string;
+  id_str: string;
+  ext_alt_text: string | null;
+  ext_media_color: ColorPalette;
+  media_url: string;
+  media_url_https: string;
+  url: string;
+  display_url: string;
+  expanded_url: string;
+  original_info: {
+    height: number;
+    width: number;
+  };
+  sizes: {
+    original: {
+      h: number;
+      resize: "fit";
+      w: number;
+    };
+  };
+  video_info: {
+    aspect_ratio: [number, number];
+    duration_millis: number;
+    variants: Array<{
+      bitrate: number;
+      content_type: string;
+      url: string;
+    }>;
+  };
+}
+type ArticleMediaInfo = ArticleImageInfo | ArticleVideoInfo;
+interface ArticleMediaEntity {
+  id: string;
+  media_key: string;
+  media_id: string;
+  media_info: ArticleMediaInfo;
+}
+interface ArticleContentBlock {
+  key: string;
+  data: Record<string, unknown>;
+  entityRanges: Array<{
+    key: number;
+    length: number;
+    offset: number;
+  }>;
+  inlineStyleRanges: Array<{
+    length: number;
+    offset: number;
+    style: string;
+  }>;
+  text: string;
+  type: string;
+}
+interface ArticleMarkdownEntity {
+  key: string;
+  value: {
+    type: "MARKDOWN";
+    mutability: "Mutable";
+    data: {
+      entityKey: string;
+      markdown: string;
+    };
+  };
+}
+interface ArticleMediaEntityRef {
+  key: string;
+  value: {
+    type: "MEDIA";
+    mutability: "Immutable";
+    data: {
+      entityKey: string;
+      mediaItems: Array<{
+        localMediaId: string;
+        mediaCategory: string;
+        mediaId: string;
+      }>;
+    };
+  };
+}
+interface ArticleTweetEntity {
+  key: string;
+  value: {
+    type: "TWEET";
+    mutability: "Immutable";
+    data: {
+      tweetId: string;
+    };
+  };
+}
+type ArticleEntity = ArticleMarkdownEntity | ArticleMediaEntityRef | ArticleTweetEntity;
+interface ArticleContent {
+  blocks: ArticleContentBlock[];
+  entityMap: ArticleEntity[];
+}
+interface Article {
+  created_at: string;
+  modified_at?: string;
+  id: string;
+  title: string;
+  preview_text: string;
+  cover_media: ArticleMediaEntity;
+  content: ArticleContent;
+  media_entities: ArticleMediaEntity[];
+}
+type EmbedCard = "tweet" | "summary" | "summary_large_image" | "player";
+interface TwitterStatus {
+  type: "status";
+  id: string;
+  url: string;
+  text: string;
+  created_at: string;
+  created_timestamp: number;
+  likes: number;
+  reposts: number;
+  quotes: number;
+  replies: number;
+  quote?: TwitterStatus | StatusTombstone;
+  poll?: Poll;
+  author: User;
+  /** Absent on posts without media, despite being marked required upstream. */
+  media?: StatusMedia;
+  raw_text: StatusRawText;
+  lang: string | null;
+  /** Only present when translation was requested via `lang`. */
+  translation?: Translation;
+  /** Omitted upstream rather than sent as `false`. */
+  possibly_sensitive?: boolean;
+  replying_to: ReplyingTo | null;
+  source: string | null;
+  embed_card: EmbedCard;
+  provider: "twitter";
+  views?: number | null;
+  bookmarks?: number | null;
+  community?: Community;
+  article?: Article;
+  is_note_tweet: boolean;
+  community_note: CommunityNote | null;
+  reposted_by: RepostedBy | null;
+  card?: Card;
+}
+type TombstoneReason = "deleted" | "suspended" | "private" | "blocked" | "unavailable";
+/** Placeholder returned in place of a quote/thread post that's no longer available. */
+interface StatusTombstone {
+  type: "tombstone";
+  provider: "twitter";
+  reason: TombstoneReason;
+  message: string;
+  id?: string;
+  url?: string;
+  author?: User;
+}
+/**
+ * A reply row inside `/2/conversation`. Documented as part of the shared
+ * multi-platform schema (its `provider` enum on FxEmbed excludes Twitter),
+ * kept here only because the API's own union allows it to appear in
+ * `SocialConversationResponse.replies`.
+ */
+interface Substatus {
+  type: "substatus";
+  parent_id: string;
+  id: string;
+  url: string;
+  text: string;
+  created_at: string;
+  created_timestamp: number;
+  likes: number;
+  reposts: number;
+  replies: number;
+  author: User;
+  media?: SubstatusMedia | null;
+  raw_text: RawText;
+  lang: string | null;
+  possibly_sensitive?: boolean;
+  replying_to?: ReplyingTo | null;
+  source: string | null;
+  embed_card?: EmbedCard;
+  provider: "instagram" | "tiktok" | "threads";
+  media_pk?: string;
+}
+type AnyStatus = TwitterStatus | StatusTombstone;
+type AnyReply = TwitterStatus | StatusTombstone | Substatus;
+interface Cursor {
+  top: string | null;
+  bottom: string | null;
+}
+/** Response for `/2/status/{id}` and `/2/thread/{id}`. */
+interface SocialThreadResponse {
+  code: number;
+  status: AnyStatus | null;
+  thread: AnyStatus[] | null;
+  author: User | null;
+}
+/** Response for `/2/conversation/{id}`. */
+interface SocialConversationResponse {
+  code: number;
+  status: AnyStatus | null;
+  thread: AnyStatus[] | null;
+  replies: AnyReply[] | null;
+  author: User | null;
+  cursor: {
+    bottom: string | null;
+  } | null;
+}
+interface SearchResults {
+  code: number;
+  results: TwitterStatus[];
+  cursor: Cursor;
+}
+interface UserListResults {
+  code: number;
+  results: User[];
+  cursor: Cursor;
+}
+/** A grouped conversation snippet, returned when `groupthreads` is set. */
+interface ThreadTimelineEntry {
+  type: "thread";
+  conversation_id: string;
+  statuses: TwitterStatus[];
+  all_status_ids?: string[];
+  /** True when `statuses` doesn't contain the full conversation. */
+  truncated: boolean;
+}
+type TimelineEntry = TwitterStatus | ThreadTimelineEntry;
+interface GroupedSearchResults {
+  code: number;
+  results: TimelineEntry[];
+  cursor: Cursor;
+}
+interface ProfileRelationshipList {
+  code: number;
+  results: User[];
+  cursor: Cursor;
+}
+interface ProfileResponse {
+  code: number;
+  message?: string;
+  user?: User;
+  /** Set to `suspended` when the user is suspended. */
+  reason?: "suspended";
+  id?: string;
+}
+interface ProfileAboutResponse {
+  code: number;
+  message?: string;
+  about_account?: AboutAccount;
+}
+interface TypeaheadTopic {
+  topic: string;
+  result_context?: {
+    display_string?: string;
+    redirect_url?: string;
+    types?: Array<{
+      type: string;
+    }>;
+  };
+}
+interface TypeaheadEvent {
+  topic: string;
+  url?: string;
+  supporting_text?: string;
+  primary_image?: {
+    url: string;
+    width?: number;
+    height?: number;
+  };
+}
+interface TypeaheadResponse {
+  code: number;
+  query: string;
+  num_results: number;
+  users: User[];
+  topics: TypeaheadTopic[];
+  events: TypeaheadEvent[];
+}
+interface Trend {
+  name: string;
+  rank: string | null;
+  context: string | null;
+  grouped_topics?: Array<{
+    name: string;
+  }>;
+}
+interface TrendsResponse {
+  code: number;
+  message?: string;
+  timeline_type: string;
+  trends: Trend[];
+  cursor: Cursor;
+}
+/** Body returned for 400 responses (invalid path/query parameters). */
+interface QueryError {
+  code: 400;
+  message: string;
+}
+//#endregion
+//#region src/v2.d.ts
+type FxTwitterV2Options = ClientOptions;
+type RankingMode = "likes" | "recency";
+type SearchFeed = "latest" | "top" | "media";
+type TypeaheadResultType = "events" | "users" | "topics";
+/** Per-call cancellation, composed with the client-level `timeout`. */
+interface AbortOptions {
+  signal?: AbortSignal;
+}
+interface GetStatusOptions extends AbortOptions {
+  /** Include `about_account` on the author when available. */
+  aboutAccount?: boolean;
+  /** ISO 639-1/639-5 target language for inline translation. */
+  lang?: string;
+}
+interface PageOptions extends AbortOptions {
+  /** Page size (1-100, API default 20). */
+  count?: number;
+  /** Pagination cursor from a prior response. */
+  cursor?: string;
+}
+interface GetStatusQuotesOptions extends PageOptions {
+  lang?: string;
+}
+interface GetConversationOptions extends AbortOptions {
+  rankingMode?: RankingMode;
+  cursor?: string;
+  aboutAccount?: boolean;
+  lang?: string;
+}
+interface GetProfileOptions extends AbortOptions {
+  aboutAccount?: boolean;
+}
+interface GetProfileStatusesOptions extends PageOptions {
+  /**
+   * Unix timestamp (seconds, or ms if >= 1e12). When set without `cursor`,
+   * the API returns 204 — and this method resolves to `null` — if no post in
+   * the page is newer than this instant.
+   */
+  since?: number;
+  withReplies?: boolean;
+  /** Return `results` as a mix of `status` and `thread` entries. */
+  groupThreads?: boolean;
+  lang?: string;
+}
+interface GetProfileArticlesOptions extends PageOptions {
+  lang?: string;
+}
+interface GetProfileMediaOptions extends PageOptions {
+  lang?: string;
+}
+interface SearchOptions extends PageOptions {
+  feed?: SearchFeed;
+  lang?: string;
+}
+interface TypeaheadOptions extends AbortOptions {
+  resultType?: TypeaheadResultType[];
+  /** Upstream `src` hint. Defaults to `search_box`. */
+  src?: string;
+}
+interface TrendsOptions extends AbortOptions {
+  /** Number of trends to return (1-50, API default 20). */
+  count?: number;
+}
+/** Builds the `id:<rest_id>` handle form accepted by the profile endpoints. */
+declare function byUserId(id: string): string;
+/** Client for the FxTwitter/FxEmbed v2 API (https://docs.fxembed.com/api/twitter/). */
+declare class FxTwitterV2 {
+  private readonly http;
+  constructor(options?: FxTwitterV2Options);
+  /** Only `/2/profile/{handle}/statuses` can answer 204, so everything else demands a body. */
+  private get;
+  /**
+   * Same as {@link get}, for the endpoints that report "no results" as a 404
+   * carrying an otherwise normal body. An empty page is a result, not an
+   * error, so it is returned rather than thrown.
+   *
+   * The API uses that same 404 for an unknown handle, which it does not
+   * distinguish from an empty timeline.
+   */
+  private getPage;
+  /** `GET /2/status/{id}` — a single post by snowflake ID. */
+  getStatus(id: string, options?: GetStatusOptions): Promise<SocialThreadResponse>;
+  /** `GET /2/status/{id}/reposts` — users who reposted a post. */
+  getStatusReposts(id: string, options?: PageOptions): Promise<UserListResults>;
+  /** `GET /2/status/{id}/quotes` — posts quoting a post. */
+  getStatusQuotes(id: string, options?: GetStatusQuotesOptions): Promise<SearchResults>;
+  /** `GET /2/thread/{id}` — a post with its unrolled thread. */
+  getThread(id: string, options?: GetStatusOptions): Promise<SocialThreadResponse>;
+  /** `GET /2/conversation/{id}` — a post, its thread, and ranked replies. */
+  getConversation(id: string, options?: GetConversationOptions): Promise<SocialConversationResponse>;
+  /**
+   * `GET /2/profile/{handle}` — a user's profile. `handle` is a username
+   * without `@`, or `byUserId(id)` for a numeric user ID.
+   */
+  getProfile(handle: string, options?: GetProfileOptions): Promise<ProfileResponse>;
+  /**
+   * `GET /2/profile/{handle}/statuses` — a user's posts. Resolves to `null`
+   * when `since` is set (without `cursor`) and nothing is newer than it.
+   */
+  getProfileStatuses(handle: string, options?: GetProfileStatusesOptions): Promise<SearchResults | GroupedSearchResults | null>;
+  /** `GET /2/profile/{handle}/articles` — a user's long-form articles. */
+  getProfileArticles(handle: string, options?: GetProfileArticlesOptions): Promise<SearchResults>;
+  /** `GET /2/profile/{handle}/about` — account metadata (based-in country, name changes). */
+  getProfileAbout(handle: string, options?: AbortOptions): Promise<ProfileAboutResponse>;
+  /** `GET /2/profile/{handle}/media` — a user's posts that contain media. */
+  getProfileMedia(handle: string, options?: GetProfileMediaOptions): Promise<SearchResults>;
+  /** `GET /2/profile/{handle}/followers` — a user's followers. */
+  getProfileFollowers(handle: string, options?: PageOptions): Promise<ProfileRelationshipList>;
+  /** `GET /2/profile/{handle}/following` — accounts a user follows. */
+  getProfileFollowing(handle: string, options?: PageOptions): Promise<ProfileRelationshipList>;
+  /** `GET /2/search` — search posts. */
+  search(query: string, options?: SearchOptions): Promise<SearchResults>;
+  /** `GET /2/typeahead` — search-box autocomplete suggestions. */
+  typeahead(query: string, options?: TypeaheadOptions): Promise<TypeaheadResponse>;
+  /** `GET /2/trends` — trending topics. */
+  trends(options?: TrendsOptions): Promise<TrendsResponse>;
+}
+//#endregion
+export { AbortOptions, type AboutAccount, type AnyMedia, type AnyReply, type AnyStatus, type Article, type ArticleContent, type ArticleContentBlock, type ArticleEntity, type ArticleImageInfo, type ArticleMarkdownEntity, type ArticleMediaEntity, type ArticleMediaEntityRef, type ArticleMediaInfo, type ArticleTweetEntity, type ArticleVideoInfo, type Birthday, type Broadcast, type BroadcastOrientation, type BroadcastState, type BroadcastThumbnail, type Card, type CardImage, type Community, type CommunityInvitesPolicy, type CommunityJoinPolicy, type CommunityNote, type Cursor, type EmbedCard, type ExternalMedia, type Facet, FxTwitterV2, FxTwitterV2Options, type GenericMedia, GetConversationOptions, GetProfileArticlesOptions, GetProfileMediaOptions, GetProfileOptions, GetProfileStatusesOptions, GetStatusOptions, GetStatusQuotesOptions, type GroupedSearchResults, type MosaicPhoto, PageOptions, type Photo, type Poll, type PollChoice, type ProfileAboutResponse, type ProfileRelationshipList, type ProfileResponse, type QueryError, RankingMode, type RawText, type ReplyingTo, type RepostedBy, SearchFeed, SearchOptions, type SearchResults, type SocialConversationResponse, type SocialThreadResponse, type StatusMedia, type StatusRawText, type StatusTombstone, type Substatus, type SubstatusMedia, type ThreadTimelineEntry, type TimelineEntry, type TombstoneReason, type Translation, type Trend, TrendsOptions, type TrendsResponse, type TwitterStatus, type TypeaheadEvent, TypeaheadOptions, type TypeaheadResponse, TypeaheadResultType, type TypeaheadTopic, type User, type UserListResults, type Verification, type VerificationType, type Video, type VideoCodec, type VideoContainer, type VideoFormat, type Website, byUserId, v2_d_exports as t };