fxtwitter 1.0.0 → 2.1.0

package/dist/v1.d.cts

@@ -1,2 +1,253 @@
-import { C as User, D as Video, E as VerificationType, O as VideoFormat, S as TwitterCard, T as Verification, _ as StatusMessage, a as AnyMedia, b as Translation, c as ExternalMedia, d as Photo, f as Poll, g as StatusMedia, h as RepostedBy, i as GetUserOptions, k as Website, l as Facet, m as RawText, n as FxTwitterV1Options, o as Author, p as PollChoice, r as GetStatusOptions, s as CommunityNote, t as FxTwitterV1, u as MosaicPhoto, v as StatusRawText, w as UserResponse, x as Tweet, y as StatusResponse } from "./v1-BKUGwGbc.cjs";
+import { t as ClientOptions } from "./http-CidaL0TV.cjs";
+//#region src/types/v1.d.ts
+interface Facet {
+  /** e.g. `url`, `mention`, `hashtag`, `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;
+}
+type VerificationType = "organization" | "government" | "individual" | null;
+interface Verification {
+  verified: boolean;
+  type: VerificationType;
+  verified_at?: string | null;
+  identity_verified?: boolean;
+  verified_by?: string;
+}
+/** The author embedded in a status. Same shape as {@link User}, plus `avatar_color`. */
+interface Author {
+  id: string;
+  name: string;
+  screen_name: string;
+  url: string;
+  description: string;
+  raw_description: RawText;
+  location: string;
+  avatar_url: string | null;
+  banner_url: string | null;
+  /** @deprecated Always `null` upstream. */
+  avatar_color?: string | null;
+  followers: number;
+  following: number;
+  likes: number;
+  media_count: number;
+  joined: string;
+  protected: boolean;
+  website: Website | null;
+  verification?: Verification;
+}
+/** The user returned by `GET /:screen_name`. Uses `tweets` where v2 uses `statuses`. */
+interface User extends Author {
+  /** Status count. Named `statuses` in the v2 API. */
+  tweets: number;
+}
+interface Translation {
+  text: string;
+  source_lang: string;
+  source_lang_en: string;
+  target_lang: string;
+  provider: string;
+}
+interface PollChoice {
+  label: string;
+  count: number;
+  /** 0-100. */
+  percentage: number;
+}
+interface Poll {
+  choices: PollChoice[];
+  total_votes: number;
+  ends_at: string;
+  time_left_en: string;
+}
+interface VideoFormat {
+  container?: "mp4" | "webm" | "m3u8";
+  codec?: "h264" | "hevc" | "vp9" | "av1";
+  bitrate?: number;
+  url: string;
+  size?: number;
+  height?: number;
+  width?: number;
+}
+interface Photo {
+  id?: string;
+  /** MIME type, e.g. `image/jpeg`. */
+  format?: string;
+  type: "photo" | "gif";
+  url: string;
+  width: number;
+  height: number;
+  transcode_url?: string | null;
+  altText?: string;
+}
+interface Video {
+  id?: string;
+  /** MIME type, e.g. `video/mp4`. */
+  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[];
+}
+interface MosaicPhoto {
+  id?: string;
+  type: "mosaic_photo";
+  url?: string;
+  width: number;
+  height: number;
+  formats: {
+    webp: string;
+    jpeg: string;
+  };
+}
+interface ExternalMedia {
+  /** Currently always `video`. */
+  type: string;
+  url: string;
+  thumbnail_url?: string;
+  height?: number;
+  width?: number;
+  duration?: number;
+}
+type AnyMedia = Photo | Video | MosaicPhoto;
+interface StatusMedia {
+  /** Preserves the original ordering across photos and videos. */
+  all?: AnyMedia[];
+  external?: ExternalMedia;
+  photos?: Photo[];
+  videos?: Video[];
+  mosaic?: MosaicPhoto;
+}
+interface CommunityNote {
+  text: string;
+  facets: Facet[];
+}
+interface RepostedBy {
+  id: string;
+  name: string;
+  screen_name: string;
+  avatar_url?: string | null;
+  url?: string;
+}
+type TwitterCard = "tweet" | "summary" | "summary_large_image" | "player";
+interface Tweet {
+  id: string;
+  url: string;
+  text: string;
+  raw_text: StatusRawText;
+  created_at: string;
+  created_timestamp: number;
+  author: Author;
+  likes: number;
+  /** Named `reposts` in the v2 API. */
+  retweets: number;
+  replies: number;
+  quotes: number;
+  views: number | null;
+  bookmarks?: number | null;
+  lang: string | null;
+  /** Screen name of the account being replied to. An object in the v2 API. */
+  replying_to: string | null;
+  /** Status ID being replied to. Folded into `replying_to` in the v2 API. */
+  replying_to_status: string | null;
+  source: string | null;
+  /** Named `embed_card` in the v2 API. */
+  twitter_card: TwitterCard;
+  provider?: string;
+  possibly_sensitive?: boolean;
+  is_note_tweet: boolean;
+  community_note: CommunityNote | null;
+  reposted_by: RepostedBy | null;
+  /** @deprecated Always `null` upstream. */
+  color?: string | null;
+  quote?: Tweet;
+  poll?: Poll;
+  /** Only present when a translation target was requested. */
+  translation?: Translation;
+  media?: StatusMedia;
+}
+/**
+ * `message` values the API maps onto its status codes: 200, 401, 404, 503
+ * and 500 respectively.
+ */
+type StatusMessage = "OK" | "PRIVATE_TWEET" | "NOT_FOUND" | "UPSTREAM_UNAVAILABLE" | "API_FAIL";
+interface StatusResponse {
+  /** Mirrors the HTTP status code. */
+  code: number;
+  message: StatusMessage | string;
+  /** `null` when the status could not be retrieved. */
+  tweet: Tweet | null;
+}
+interface UserResponse {
+  /** Mirrors the HTTP status code. */
+  code: number;
+  message: string;
+  /** Omitted entirely when the user could not be retrieved. */
+  user?: User;
+  /** Set to `suspended` when the account is suspended. */
+  reason?: "suspended";
+}
+//#endregion
+//#region src/v1.d.ts
+type FxTwitterV1Options = ClientOptions & {
+  /** Suppresses the one-time deprecation warning emitted on construction. */
+  silenceDeprecationWarning?: boolean;
+};
+interface GetStatusOptions {
+  /**
+   * Included in the URL for readability only. The API resolves the status from
+   * `id` alone and never validates this, so a wrong handle still succeeds.
+   */
+  screenName?: string;
+  /**
+   * Language to translate the status into, as an ISO 639-1 code (`es`) or a
+   * locale (`zh-cn`). Adds a `translation` object to the returned status.
+   */
+  translateTo?: string;
+  /** Per-call cancellation, composed with the client-level `timeout`. */
+  signal?: AbortSignal;
+}
+interface GetUserOptions {
+  signal?: AbortSignal;
+}
+/**
+ * Client for the legacy FxTwitter v1 API.
+ *
+ * @deprecated Use {@link import("./v2").FxTwitterV2} instead. v1 is kept only
+ * for backwards compatibility and does not receive new features.
+ */
+declare class FxTwitterV1 {
+  private readonly http;
+  constructor(options?: FxTwitterV1Options);
+  /**
+   * Fetches a single status by its snowflake ID.
+   *
+   * `GET /status/:id`, `GET /status/:id/:language`,
+   * `GET /:handle/status/:id`, `GET /:handle/status/:id/:language`
+   */
+  getStatus(id: string, options?: GetStatusOptions): Promise<StatusResponse>;
+  /** Fetches a user profile by handle (`GET /:handle`). */
+  getUser(screenName: string, options?: GetUserOptions): Promise<UserResponse>;
+}
+//#endregion
 export { type AnyMedia, type Author, type CommunityNote, type ExternalMedia, type Facet, FxTwitterV1, FxTwitterV1Options, GetStatusOptions, GetUserOptions, type MosaicPhoto, type Photo, type Poll, type PollChoice, type RawText, type RepostedBy, type StatusMedia, type StatusMessage, type StatusRawText, type StatusResponse, type Translation, type Tweet, type TwitterCard, type User, type UserResponse, type Verification, type VerificationType, type Video, type VideoFormat, type Website };

package/dist/v1.d.mts

@@ -1,2 +1,253 @@
-import { C as User, D as Video, E as VerificationType, O as VideoFormat, S as TwitterCard, T as Verification, _ as StatusMessage, a as AnyMedia, b as Translation, c as ExternalMedia, d as Photo, f as Poll, g as StatusMedia, h as RepostedBy, i as GetUserOptions, k as Website, l as Facet, m as RawText, n as FxTwitterV1Options, o as Author, p as PollChoice, r as GetStatusOptions, s as CommunityNote, t as FxTwitterV1, u as MosaicPhoto, v as StatusRawText, w as UserResponse, x as Tweet, y as StatusResponse } from "./v1-BKUGwGbc.mjs";
+import { t as ClientOptions } from "./http-CidaL0TV.mjs";
+//#region src/types/v1.d.ts
+interface Facet {
+  /** e.g. `url`, `mention`, `hashtag`, `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;
+}
+type VerificationType = "organization" | "government" | "individual" | null;
+interface Verification {
+  verified: boolean;
+  type: VerificationType;
+  verified_at?: string | null;
+  identity_verified?: boolean;
+  verified_by?: string;
+}
+/** The author embedded in a status. Same shape as {@link User}, plus `avatar_color`. */
+interface Author {
+  id: string;
+  name: string;
+  screen_name: string;
+  url: string;
+  description: string;
+  raw_description: RawText;
+  location: string;
+  avatar_url: string | null;
+  banner_url: string | null;
+  /** @deprecated Always `null` upstream. */
+  avatar_color?: string | null;
+  followers: number;
+  following: number;
+  likes: number;
+  media_count: number;
+  joined: string;
+  protected: boolean;
+  website: Website | null;
+  verification?: Verification;
+}
+/** The user returned by `GET /:screen_name`. Uses `tweets` where v2 uses `statuses`. */
+interface User extends Author {
+  /** Status count. Named `statuses` in the v2 API. */
+  tweets: number;
+}
+interface Translation {
+  text: string;
+  source_lang: string;
+  source_lang_en: string;
+  target_lang: string;
+  provider: string;
+}
+interface PollChoice {
+  label: string;
+  count: number;
+  /** 0-100. */
+  percentage: number;
+}
+interface Poll {
+  choices: PollChoice[];
+  total_votes: number;
+  ends_at: string;
+  time_left_en: string;
+}
+interface VideoFormat {
+  container?: "mp4" | "webm" | "m3u8";
+  codec?: "h264" | "hevc" | "vp9" | "av1";
+  bitrate?: number;
+  url: string;
+  size?: number;
+  height?: number;
+  width?: number;
+}
+interface Photo {
+  id?: string;
+  /** MIME type, e.g. `image/jpeg`. */
+  format?: string;
+  type: "photo" | "gif";
+  url: string;
+  width: number;
+  height: number;
+  transcode_url?: string | null;
+  altText?: string;
+}
+interface Video {
+  id?: string;
+  /** MIME type, e.g. `video/mp4`. */
+  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[];
+}
+interface MosaicPhoto {
+  id?: string;
+  type: "mosaic_photo";
+  url?: string;
+  width: number;
+  height: number;
+  formats: {
+    webp: string;
+    jpeg: string;
+  };
+}
+interface ExternalMedia {
+  /** Currently always `video`. */
+  type: string;
+  url: string;
+  thumbnail_url?: string;
+  height?: number;
+  width?: number;
+  duration?: number;
+}
+type AnyMedia = Photo | Video | MosaicPhoto;
+interface StatusMedia {
+  /** Preserves the original ordering across photos and videos. */
+  all?: AnyMedia[];
+  external?: ExternalMedia;
+  photos?: Photo[];
+  videos?: Video[];
+  mosaic?: MosaicPhoto;
+}
+interface CommunityNote {
+  text: string;
+  facets: Facet[];
+}
+interface RepostedBy {
+  id: string;
+  name: string;
+  screen_name: string;
+  avatar_url?: string | null;
+  url?: string;
+}
+type TwitterCard = "tweet" | "summary" | "summary_large_image" | "player";
+interface Tweet {
+  id: string;
+  url: string;
+  text: string;
+  raw_text: StatusRawText;
+  created_at: string;
+  created_timestamp: number;
+  author: Author;
+  likes: number;
+  /** Named `reposts` in the v2 API. */
+  retweets: number;
+  replies: number;
+  quotes: number;
+  views: number | null;
+  bookmarks?: number | null;
+  lang: string | null;
+  /** Screen name of the account being replied to. An object in the v2 API. */
+  replying_to: string | null;
+  /** Status ID being replied to. Folded into `replying_to` in the v2 API. */
+  replying_to_status: string | null;
+  source: string | null;
+  /** Named `embed_card` in the v2 API. */
+  twitter_card: TwitterCard;
+  provider?: string;
+  possibly_sensitive?: boolean;
+  is_note_tweet: boolean;
+  community_note: CommunityNote | null;
+  reposted_by: RepostedBy | null;
+  /** @deprecated Always `null` upstream. */
+  color?: string | null;
+  quote?: Tweet;
+  poll?: Poll;
+  /** Only present when a translation target was requested. */
+  translation?: Translation;
+  media?: StatusMedia;
+}
+/**
+ * `message` values the API maps onto its status codes: 200, 401, 404, 503
+ * and 500 respectively.
+ */
+type StatusMessage = "OK" | "PRIVATE_TWEET" | "NOT_FOUND" | "UPSTREAM_UNAVAILABLE" | "API_FAIL";
+interface StatusResponse {
+  /** Mirrors the HTTP status code. */
+  code: number;
+  message: StatusMessage | string;
+  /** `null` when the status could not be retrieved. */
+  tweet: Tweet | null;
+}
+interface UserResponse {
+  /** Mirrors the HTTP status code. */
+  code: number;
+  message: string;
+  /** Omitted entirely when the user could not be retrieved. */
+  user?: User;
+  /** Set to `suspended` when the account is suspended. */
+  reason?: "suspended";
+}
+//#endregion
+//#region src/v1.d.ts
+type FxTwitterV1Options = ClientOptions & {
+  /** Suppresses the one-time deprecation warning emitted on construction. */
+  silenceDeprecationWarning?: boolean;
+};
+interface GetStatusOptions {
+  /**
+   * Included in the URL for readability only. The API resolves the status from
+   * `id` alone and never validates this, so a wrong handle still succeeds.
+   */
+  screenName?: string;
+  /**
+   * Language to translate the status into, as an ISO 639-1 code (`es`) or a
+   * locale (`zh-cn`). Adds a `translation` object to the returned status.
+   */
+  translateTo?: string;
+  /** Per-call cancellation, composed with the client-level `timeout`. */
+  signal?: AbortSignal;
+}
+interface GetUserOptions {
+  signal?: AbortSignal;
+}
+/**
+ * Client for the legacy FxTwitter v1 API.
+ *
+ * @deprecated Use {@link import("./v2").FxTwitterV2} instead. v1 is kept only
+ * for backwards compatibility and does not receive new features.
+ */
+declare class FxTwitterV1 {
+  private readonly http;
+  constructor(options?: FxTwitterV1Options);
+  /**
+   * Fetches a single status by its snowflake ID.
+   *
+   * `GET /status/:id`, `GET /status/:id/:language`,
+   * `GET /:handle/status/:id`, `GET /:handle/status/:id/:language`
+   */
+  getStatus(id: string, options?: GetStatusOptions): Promise<StatusResponse>;
+  /** Fetches a user profile by handle (`GET /:handle`). */
+  getUser(screenName: string, options?: GetUserOptions): Promise<UserResponse>;
+}
+//#endregion
 export { type AnyMedia, type Author, type CommunityNote, type ExternalMedia, type Facet, FxTwitterV1, FxTwitterV1Options, GetStatusOptions, GetUserOptions, type MosaicPhoto, type Photo, type Poll, type PollChoice, type RawText, type RepostedBy, type StatusMedia, type StatusMessage, type StatusRawText, type StatusResponse, type Translation, type Tweet, type TwitterCard, type User, type UserResponse, type Verification, type VerificationType, type Video, type VideoFormat, type Website };

package/dist/v1.mjs

@@ -1,2 +1,2 @@
-import { t as FxTwitterV1 } from "./v1-KUPCoHD9.mjs";
+import { t as FxTwitterV1 } from "./v1-ByqsBlpO.mjs";
 export { FxTwitterV1 };

package/dist/v2.cjs

@@ -0,0 +1,183 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_http = require("./http-Cs4GJeg-.cjs");
+//#region src/v2.ts
+/** Builds the `id:<rest_id>` handle form accepted by the profile endpoints. */
+function byUserId(id) {
+	return `id:${id}`;
+}
+/**
+* Recovers the body of a 404 that carries a well-formed, empty result page,
+* which is how the list endpoints report "no results or timeline unavailable".
+*/
+function emptyPage(error) {
+	if (!(error instanceof require_http.FxTwitterError) || error.status !== 404) return null;
+	const body = error.body;
+	if (typeof body !== "object" || body === null) return null;
+	const results = body.results;
+	return Array.isArray(results) ? body : null;
+}
+/** Client for the FxTwitter/FxEmbed v2 API (https://docs.fxembed.com/api/twitter/). */
+var FxTwitterV2 = class {
+	http;
+	constructor(options = {}) {
+		this.http = new require_http.HttpClient(options);
+	}
+	/** Only `/2/profile/{handle}/statuses` can answer 204, so everything else demands a body. */
+	async get(path, query, signal) {
+		const body = await this.http.get({
+			path,
+			query,
+			signal
+		});
+		if (body === null) throw new require_http.FxTwitterError("The API returned an empty response");
+		return body;
+	}
+	/**
+	* 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.
+	*/
+	async getPage(path, query, signal) {
+		try {
+			return await this.get(path, query, signal);
+		} catch (error) {
+			const page = emptyPage(error);
+			if (page) return page;
+			throw error;
+		}
+	}
+	/** `GET /2/status/{id}` — a single post by snowflake ID. */
+	getStatus(id, options = {}) {
+		return this.get(`/2/status/${encodeURIComponent(id)}`, {
+			about_account: options.aboutAccount ? "1" : void 0,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/status/{id}/reposts` — users who reposted a post. */
+	getStatusReposts(id, options = {}) {
+		return this.getPage(`/2/status/${encodeURIComponent(id)}/reposts`, {
+			count: options.count,
+			cursor: options.cursor
+		}, options.signal);
+	}
+	/** `GET /2/status/{id}/quotes` — posts quoting a post. */
+	getStatusQuotes(id, options = {}) {
+		return this.getPage(`/2/status/${encodeURIComponent(id)}/quotes`, {
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/thread/{id}` — a post with its unrolled thread. */
+	getThread(id, options = {}) {
+		return this.get(`/2/thread/${encodeURIComponent(id)}`, {
+			about_account: options.aboutAccount ? "1" : void 0,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/conversation/{id}` — a post, its thread, and ranked replies. */
+	getConversation(id, options = {}) {
+		return this.get(`/2/conversation/${encodeURIComponent(id)}`, {
+			ranking_mode: options.rankingMode,
+			cursor: options.cursor,
+			about_account: options.aboutAccount ? "1" : void 0,
+			lang: options.lang
+		}, options.signal);
+	}
+	/**
+	* `GET /2/profile/{handle}` — a user's profile. `handle` is a username
+	* without `@`, or `byUserId(id)` for a numeric user ID.
+	*/
+	getProfile(handle, options = {}) {
+		return this.get(`/2/profile/${encodeURIComponent(handle)}`, { about_account: options.aboutAccount ? "1" : void 0 }, options.signal);
+	}
+	/**
+	* `GET /2/profile/{handle}/statuses` — a user's posts. Resolves to `null`
+	* when `since` is set (without `cursor`) and nothing is newer than it.
+	*/
+	async getProfileStatuses(handle, options = {}) {
+		try {
+			return await this.http.get({
+				path: `/2/profile/${encodeURIComponent(handle)}/statuses`,
+				query: {
+					count: options.count,
+					cursor: options.cursor,
+					since: options.since,
+					with_replies: options.withReplies ? "1" : void 0,
+					groupthreads: options.groupThreads ? "1" : void 0,
+					lang: options.lang
+				},
+				signal: options.signal
+			});
+		} catch (error) {
+			const page = emptyPage(error);
+			if (page) return page;
+			throw error;
+		}
+	}
+	/** `GET /2/profile/{handle}/articles` — a user's long-form articles. */
+	getProfileArticles(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/articles`, {
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/profile/{handle}/about` — account metadata (based-in country, name changes). */
+	getProfileAbout(handle, options = {}) {
+		return this.get(`/2/profile/${encodeURIComponent(handle)}/about`, void 0, options.signal);
+	}
+	/** `GET /2/profile/{handle}/media` — a user's posts that contain media. */
+	getProfileMedia(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/media`, {
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/profile/{handle}/followers` — a user's followers. */
+	getProfileFollowers(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/followers`, {
+			count: options.count,
+			cursor: options.cursor
+		}, options.signal);
+	}
+	/** `GET /2/profile/{handle}/following` — accounts a user follows. */
+	getProfileFollowing(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/following`, {
+			count: options.count,
+			cursor: options.cursor
+		}, options.signal);
+	}
+	/** `GET /2/search` — search posts. */
+	search(query, options = {}) {
+		return this.getPage("/2/search", {
+			q: query,
+			feed: options.feed,
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/typeahead` — search-box autocomplete suggestions. */
+	typeahead(query, options = {}) {
+		return this.get("/2/typeahead", {
+			q: query,
+			result_type: options.resultType?.join(","),
+			src: options.src
+		}, options.signal);
+	}
+	/** `GET /2/trends` — trending topics. */
+	trends(options = {}) {
+		return this.get("/2/trends", {
+			type: "trending",
+			count: options.count
+		}, options.signal);
+	}
+};
+//#endregion
+exports.FxTwitterV2 = FxTwitterV2;
+exports.byUserId = byUserId;