fxtwitter 0.0.0-reserved → 2.0.0

package/dist/index.d.mts

@@ -0,0 +1,58 @@
+import { t as ClientOptions } from "./http-CidaL0TV.mjs";
+import { AnyMedia, Author, CommunityNote, ExternalMedia, Facet, FxTwitterV1, FxTwitterV1Options, GetStatusOptions, GetUserOptions, MosaicPhoto, Photo, Poll, PollChoice, RawText, RepostedBy, StatusMedia, StatusMessage, StatusRawText, StatusResponse, Translation, Tweet, TwitterCard, User, UserResponse, Verification, VerificationType, Video, VideoFormat, Website } from "./v1.mjs";
+import { FxTwitterV2, FxTwitterV2Options, byUserId, t as v2_d_exports } from "./v2.mjs";
+//#region src/client.d.ts
+type FxTwitterOptions = ClientOptions & {
+  /** Overrides applied only to the v1 client. */
+  v1?: Pick<ClientOptions, "baseUrl"> & {
+    /** Suppresses the one-time deprecation warning emitted when `v1` is first accessed. */
+    silenceDeprecationWarning?: boolean;
+  };
+  /** Overrides applied only to the v2 client. */
+  v2?: Pick<ClientOptions, "baseUrl">;
+};
+/**
+ * Combined client exposing every API version.
+ *
+ * Prefer importing a single version when you only need one — `FxTwitterV2`
+ * from `fxtwitter/v2` — and reach for this only when you use both.
+ *
+ * ```ts
+ * const fx = new FxTwitter();
+ * const { status } = await fx.v2.getStatus("20");
+ * const { tweet } = await fx.v1.getStatus("20");
+ * ```
+ */
+declare class FxTwitter {
+  readonly v2: FxTwitterV2;
+  private readonly v1Options;
+  private v1Client?;
+  constructor(options?: FxTwitterOptions);
+  /**
+   * The legacy v1 client, constructed on first access so its deprecation
+   * warning is only emitted if you actually use it.
+   *
+   * @deprecated Use {@link FxTwitter.v2} instead.
+   */
+  get v1(): FxTwitterV1;
+}
+//#endregion
+//#region src/errors.d.ts
+interface FxTwitterErrorOptions {
+  /** HTTP status code returned by the API. */
+  status?: number;
+  /** `code` field from the JSON response body (mirrors the HTTP status). */
+  code?: number;
+  /** Parsed response body, when available. */
+  body?: unknown;
+  cause?: unknown;
+}
+/** Thrown for any non-2xx response, network failure, timeout, or unparsable body. */
+declare class FxTwitterError extends Error {
+  readonly status?: number;
+  readonly code?: number;
+  readonly body?: unknown;
+  constructor(message: string, options?: FxTwitterErrorOptions);
+}
+//#endregion
+export { type AnyMedia, type Author, type ClientOptions, type CommunityNote, type ExternalMedia, type Facet, FxTwitter, FxTwitterError, type FxTwitterErrorOptions, type FxTwitterOptions, FxTwitterV1, type FxTwitterV1Options, FxTwitterV2, type FxTwitterV2Options, type GetStatusOptions, type 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 v2_d_exports as V2, type Verification, type VerificationType, type Video, type VideoFormat, type Website, byUserId };

package/dist/index.mjs

@@ -0,0 +1,45 @@
+import { t as FxTwitterV1 } from "./v1-ByqsBlpO.mjs";
+import { n as FxTwitterError } from "./http-BTdKgEdX.mjs";
+import { FxTwitterV2, byUserId } from "./v2.mjs";
+//#region src/client.ts
+/**
+* Combined client exposing every API version.
+*
+* Prefer importing a single version when you only need one — `FxTwitterV2`
+* from `fxtwitter/v2` — and reach for this only when you use both.
+*
+* ```ts
+* const fx = new FxTwitter();
+* const { status } = await fx.v2.getStatus("20");
+* const { tweet } = await fx.v1.getStatus("20");
+* ```
+*/
+var FxTwitter = class {
+	v2;
+	v1Options;
+	v1Client;
+	constructor(options = {}) {
+		const { v1, v2, ...shared } = options;
+		this.v2 = new FxTwitterV2({
+			...shared,
+			baseUrl: v2?.baseUrl
+		});
+		this.v1Options = {
+			...shared,
+			baseUrl: v1?.baseUrl,
+			silenceDeprecationWarning: v1?.silenceDeprecationWarning
+		};
+	}
+	/**
+	* The legacy v1 client, constructed on first access so its deprecation
+	* warning is only emitted if you actually use it.
+	*
+	* @deprecated Use {@link FxTwitter.v2} instead.
+	*/
+	get v1() {
+		this.v1Client ??= new FxTwitterV1(this.v1Options);
+		return this.v1Client;
+	}
+};
+//#endregion
+export { FxTwitter, FxTwitterError, FxTwitterV1, FxTwitterV2, byUserId };

package/dist/v1-BFKgLuJi.cjs

@@ -0,0 +1,92 @@
+const require_http = require("./http-Cs4GJeg-.cjs");
+//#region src/deprecation.ts
+const emitted = /* @__PURE__ */ new Set();
+/**
+* Emits a deprecation warning once per process, the way Node's own deprecated
+* APIs (and libraries such as discord.js) do — so `--no-deprecation` and
+* `--throw-deprecation` apply, and repeated construction doesn't spam the
+* console. Falls back to `console.warn` in runtimes without
+* `process.emitWarning`.
+*/
+function emitDeprecationWarning(code, message) {
+	if (emitted.has(code)) return;
+	emitted.add(code);
+	const proc = globalThis.process;
+	if (typeof proc?.emitWarning === "function") {
+		proc.emitWarning(message, {
+			type: "DeprecationWarning",
+			code
+		});
+		return;
+	}
+	console.warn(`DeprecationWarning [${code}]: ${message}`);
+}
+//#endregion
+//#region src/v1.ts
+/**
+* The API resolves a status from the first 2-20 digit run in the path segment,
+* and answers anything else with its embed HTML at HTTP 200 rather than JSON.
+*/
+const STATUS_ID_PATTERN = /^\d{2,20}$/;
+/**
+* Handles are matched as `\w{1,15}` upstream; anything else is redirected to
+* the project's GitHub page instead of returning JSON.
+*/
+const HANDLE_PATTERN = /^\w{1,15}$/;
+const DEPRECATION_MESSAGE = "FxTwitterV1 targets the legacy FxTwitter v1 API, which is kept only for backwards compatibility and does not receive new features. Use FxTwitterV2 (import from \"fxtwitter/v2\") instead.";
+/**
+* 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.
+*/
+var FxTwitterV1 = class {
+	http;
+	constructor(options = {}) {
+		if (!options.silenceDeprecationWarning) emitDeprecationWarning("FXTWITTER_V1_DEPRECATED", DEPRECATION_MESSAGE);
+		this.http = new require_http.HttpClient(options);
+	}
+	/**
+	* Fetches a single status by its snowflake ID.
+	*
+	* `GET /status/:id`, `GET /status/:id/:language`,
+	* `GET /:handle/status/:id`, `GET /:handle/status/:id/:language`
+	*/
+	async getStatus(id, options = {}) {
+		if (!STATUS_ID_PATTERN.test(id)) throw new require_http.FxTwitterError(`Invalid status ID ${JSON.stringify(id)}: expected 2-20 digits`);
+		if (options.screenName !== void 0 && options.screenName.trim() === "") throw new require_http.FxTwitterError("screenName must not be empty");
+		const segments = [
+			options.screenName,
+			"status",
+			id,
+			options.translateTo
+		].filter((segment) => segment !== void 0);
+		return requireBody(await this.http.get({
+			path: `/${segments.map(encodeURIComponent).join("/")}`,
+			signal: options.signal
+		}));
+	}
+	/** Fetches a user profile by handle (`GET /:handle`). */
+	async getUser(screenName, options = {}) {
+		assertHandle(screenName);
+		return requireBody(await this.http.get({
+			path: `/${encodeURIComponent(screenName)}`,
+			signal: options.signal
+		}));
+	}
+};
+function assertHandle(handle) {
+	if (!HANDLE_PATTERN.test(handle)) throw new require_http.FxTwitterError(`Invalid handle ${JSON.stringify(handle)}: expected 1-15 letters, digits or underscores, without a leading @`);
+}
+/** v1 never answers 204, so an empty body here means something went wrong. */
+function requireBody(body) {
+	if (body === null) throw new require_http.FxTwitterError("The API returned an empty response");
+	return body;
+}
+//#endregion
+Object.defineProperty(exports, "FxTwitterV1", {
+	enumerable: true,
+	get: function() {
+		return FxTwitterV1;
+	}
+});

package/dist/v1-ByqsBlpO.mjs

@@ -0,0 +1,87 @@
+import { n as FxTwitterError, t as HttpClient } from "./http-BTdKgEdX.mjs";
+//#region src/deprecation.ts
+const emitted = /* @__PURE__ */ new Set();
+/**
+* Emits a deprecation warning once per process, the way Node's own deprecated
+* APIs (and libraries such as discord.js) do — so `--no-deprecation` and
+* `--throw-deprecation` apply, and repeated construction doesn't spam the
+* console. Falls back to `console.warn` in runtimes without
+* `process.emitWarning`.
+*/
+function emitDeprecationWarning(code, message) {
+	if (emitted.has(code)) return;
+	emitted.add(code);
+	const proc = globalThis.process;
+	if (typeof proc?.emitWarning === "function") {
+		proc.emitWarning(message, {
+			type: "DeprecationWarning",
+			code
+		});
+		return;
+	}
+	console.warn(`DeprecationWarning [${code}]: ${message}`);
+}
+//#endregion
+//#region src/v1.ts
+/**
+* The API resolves a status from the first 2-20 digit run in the path segment,
+* and answers anything else with its embed HTML at HTTP 200 rather than JSON.
+*/
+const STATUS_ID_PATTERN = /^\d{2,20}$/;
+/**
+* Handles are matched as `\w{1,15}` upstream; anything else is redirected to
+* the project's GitHub page instead of returning JSON.
+*/
+const HANDLE_PATTERN = /^\w{1,15}$/;
+const DEPRECATION_MESSAGE = "FxTwitterV1 targets the legacy FxTwitter v1 API, which is kept only for backwards compatibility and does not receive new features. Use FxTwitterV2 (import from \"fxtwitter/v2\") instead.";
+/**
+* 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.
+*/
+var FxTwitterV1 = class {
+	http;
+	constructor(options = {}) {
+		if (!options.silenceDeprecationWarning) emitDeprecationWarning("FXTWITTER_V1_DEPRECATED", DEPRECATION_MESSAGE);
+		this.http = new HttpClient(options);
+	}
+	/**
+	* Fetches a single status by its snowflake ID.
+	*
+	* `GET /status/:id`, `GET /status/:id/:language`,
+	* `GET /:handle/status/:id`, `GET /:handle/status/:id/:language`
+	*/
+	async getStatus(id, options = {}) {
+		if (!STATUS_ID_PATTERN.test(id)) throw new FxTwitterError(`Invalid status ID ${JSON.stringify(id)}: expected 2-20 digits`);
+		if (options.screenName !== void 0 && options.screenName.trim() === "") throw new FxTwitterError("screenName must not be empty");
+		const segments = [
+			options.screenName,
+			"status",
+			id,
+			options.translateTo
+		].filter((segment) => segment !== void 0);
+		return requireBody(await this.http.get({
+			path: `/${segments.map(encodeURIComponent).join("/")}`,
+			signal: options.signal
+		}));
+	}
+	/** Fetches a user profile by handle (`GET /:handle`). */
+	async getUser(screenName, options = {}) {
+		assertHandle(screenName);
+		return requireBody(await this.http.get({
+			path: `/${encodeURIComponent(screenName)}`,
+			signal: options.signal
+		}));
+	}
+};
+function assertHandle(handle) {
+	if (!HANDLE_PATTERN.test(handle)) throw new FxTwitterError(`Invalid handle ${JSON.stringify(handle)}: expected 1-15 letters, digits or underscores, without a leading @`);
+}
+/** v1 never answers 204, so an empty body here means something went wrong. */
+function requireBody(body) {
+	if (body === null) throw new FxTwitterError("The API returned an empty response");
+	return body;
+}
+//#endregion
+export { FxTwitterV1 as t };

package/dist/v1.cjs

@@ -0,0 +1,3 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_v1 = require("./v1-BFKgLuJi.cjs");
+exports.FxTwitterV1 = require_v1.FxTwitterV1;

package/dist/v1.d.cts

@@ -0,0 +1,253 @@
+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 };