finish rust rewrite, add docker, drop python

crates/x-media/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "x-media"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+reqwest = { version = "0.13", features = ["json", "query", "form"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+regex = "1.12"
+html-escape = "0.2"
+url = "2.5.2"
+bytes = "1"
+zip = "2"
+tempfile = "3"
+log = "0.4"
+tokio = { version = "1.40", features = ["time"] }
+
+[dev-dependencies]
+tokio = { version = "1.40", features = ["macros", "rt-multi-thread"] }
+dotenv = "0.15"

crates/x-media/examples/fetch.rs

@@ -0,0 +1,10 @@
+use x_media::site;
+
+#[tokio::main]
+async fn main() {
+    let url = std::env::args()
+        .nth(1)
+        .expect("usage: cargo run -p x-media --example fetch -- <url>");
+    let result = site::fetch(&url).await;
+    println!("{result:#?}");
+}

crates/x-media/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod media;
+pub mod site;

crates/x-media/src/media.rs

@@ -0,0 +1,37 @@
+impl Media {
+    pub fn url(&self) -> &str {
+        match self {
+            Media::Illustration { url, .. } => url,
+            Media::Video { url, .. } => url,
+            Media::Animated { url, .. } => url,
+        }
+    }
+
+    pub fn thumbnail_url(&self) -> Option<&str> {
+        match self {
+            Media::Illustration { thumbnail_url, .. } => thumbnail_url.as_deref(),
+            Media::Video { thumbnail_url, .. } => Some(thumbnail_url),
+            Media::Animated { thumbnail_url, .. } => Some(thumbnail_url),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub enum Media {
+    Illustration {
+        title: Option<String>,
+        url: String,
+        thumbnail_url: Option<String>,
+        fallback_url: Option<String>,
+    },
+    Video {
+        title: Option<String>,
+        url: String,
+        thumbnail_url: String,
+    },
+    Animated {
+        title: Option<String>,
+        url: String,
+        thumbnail_url: String,
+    },
+}

crates/x-media/src/site/bsky/interface.rs

@@ -0,0 +1,272 @@
+use super::model;
+use crate::media::Media;
+use crate::site::{FetchError, Fetched};
+use html_escape::encode_text;
+use regex::Regex;
+use std::sync::LazyLock;
+
+pub static PATTERN: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new(r"bsky\.app/profile/([\w.\-:]+)/post/([\w.\-~]+)").unwrap()
+});
+
+pub fn enabled() -> bool {
+    true
+}
+
+pub async fn fetch_from_url(url: &str) -> Result<Fetched, FetchError> {
+    let caps = PATTERN.captures(url).ok_or(FetchError::NotFound)?;
+    let handle = caps.get(1).map(|m| m.as_str()).ok_or(FetchError::NotFound)?;
+    let rkey = caps.get(2).map(|m| m.as_str()).ok_or(FetchError::NotFound)?;
+    Ok(fetch(handle, rkey).await?.into())
+}
+
+/// Fetches a post thread by handle or DID (`at://` URIs work for both).
+pub async fn fetch(handle: &str, rkey: &str) -> Result<Post, FetchError> {
+    let response = crate::site::CLIENT
+        .get(API_URL)
+        .query(&[
+            ("uri", format!("at://{handle}/app.bsky.feed.post/{rkey}")),
+            ("depth", "0".to_string()),
+        ])
+        .send()
+        .await?;
+    let text = response.text().await?;
+    Ok(Post::from_json(&text, rkey.to_string())?)
+}
+
+#[derive(Debug)]
+pub struct Post {
+    id: String,
+    author: String,
+    author_id: String,
+    text: String,
+    media: Vec<Media>,
+    sensitive: bool,
+}
+
+impl Post {
+    fn url(&self) -> String {
+        format!("{}/post/{}", self.author_url(), self.id)
+    }
+
+    fn author_url(&self) -> String {
+        format!("https://bsky.app/profile/{}", self.author_id)
+    }
+
+    pub fn caption(&self) -> String {
+        format!(
+            "{url}\n<a href=\"{author_url}\">{author}</a>: {text}",
+            url = self.url(),
+            author_url = self.author_url(),
+            author = encode_text(&self.author),
+            text = encode_text(&self.text),
+        )
+    }
+
+    pub fn from_json(raw_json: &str, id: String) -> Result<Self, FetchError> {
+        let json: serde_json::Value = serde_json::from_str(raw_json).map_err(FetchError::Json)?;
+        let json: model::Info = serde_json::from_value(json).map_err(FetchError::Json)?;
+        match json.thread {
+            model::Thread::Post { post } => {
+                let text = post.record.text;
+                let author = post.author.display_name.unwrap_or_default();
+                let author_id = post.author.handle;
+                let mut media = vec![];
+                if let Some(embed) = post.embed {
+                    match embed {
+                        model::Media::Images { images } => {
+                            media.extend(images.into_iter().map(|image| Media::Illustration {
+                                title: None,
+                                url: image.fullsize,
+                                thumbnail_url: Some(image.thumb),
+                                fallback_url: None,
+                            }));
+                        }
+                        model::Media::Video {
+                            playlist,
+                            thumbnail,
+                        } => {
+                            media.push(Media::Video {
+                                title: None,
+                                url: playlist,
+                                thumbnail_url: thumbnail,
+                            });
+                        }
+                        model::Media::External => {}
+                    }
+                }
+                let sensitive = post
+                    .labels
+                    .iter()
+                    .any(|label| SENSITIVE_LABEL.contains(&label.val.as_str()));
+                Ok(Post {
+                    id,
+                    author,
+                    author_id,
+                    text,
+                    media,
+                    sensitive,
+                })
+            }
+            model::Thread::NotFound => Err(FetchError::NotFound),
+            model::Thread::Blocked => Err(FetchError::Blocked),
+        }
+    }
+}
+
+impl From<Post> for Fetched {
+    fn from(post: Post) -> Self {
+        let url = post.url();
+        let author_url = post.author_url();
+        let render_data = Some(crate::site::RenderData {
+            url: url.clone(),
+            author: encode_text(&post.author).into_owned(),
+            author_url: author_url.clone(),
+            title: encode_text(&post.text).into_owned(),
+            tags: String::new(),
+        });
+        Fetched {
+            source_url: url,
+            caption: post.caption(),
+            title: post.text.clone(),
+            media: post.media,
+            sensitive: post.sensitive,
+            render_data,
+            _keep_alive: None,
+        }
+    }
+}
+
+const API_URL: &str = "https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread";
+const SENSITIVE_LABEL: [&str; 4] = ["sexual", "nudity", "porn", "graphic-media"];
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn thread_json(post_json: serde_json::Value) -> serde_json::Value {
+        serde_json::json!({ "thread": post_json })
+    }
+
+    #[test]
+    fn pattern_matches_handle_and_did() {
+        let cases = [
+            (
+                "https://bsky.app/profile/user.bsky.social/post/3laoveufjv224",
+                "user.bsky.social",
+                "3laoveufjv224",
+            ),
+            (
+                "https://bsky.app/profile/did:plc:abc123def/post/3xxxx",
+                "did:plc:abc123def",
+                "3xxxx",
+            ),
+        ];
+        for (url, handle, rkey) in cases {
+            let caps = PATTERN.captures(url).unwrap_or_else(|| panic!("{url}"));
+            assert_eq!(caps.get(1).unwrap().as_str(), handle);
+            assert_eq!(caps.get(2).unwrap().as_str(), rkey);
+        }
+    }
+
+    #[test]
+    fn pattern_rejects_non_post_urls() {
+        for url in [
+            "https://bsky.app/profile/user.bsky.social",
+            "https://bsky.app/profile/user.bsky.social/posts",
+            "https://x.com/user/status/123",
+        ] {
+            assert!(!PATTERN.is_match(url), "{url}");
+        }
+    }
+
+    #[test]
+    fn from_json_images_with_missing_defaults() {
+        let raw = thread_json(serde_json::json!({
+            "$type": "app.bsky.feed.defs#threadViewPost",
+            "post": {
+                "author": { "handle": "user.bsky.social" },
+                "record": { "$type": "app.bsky.feed.post", "text": "hello <world>" },
+                "embed": {
+                    "$type": "app.bsky.embed.images#view",
+                    "images": [
+                        { "thumb": "https://cdn.bsky.app/img/thumb", "fullsize": "https://cdn.bsky.app/img/full", "alt": "" }
+                    ]
+                }
+            }
+        }));
+        let post = Post::from_json(&raw.to_string(), "3xxxx".into()).unwrap();
+        let fetched: Fetched = post.into();
+        assert_eq!(fetched.source_url, "https://bsky.app/profile/user.bsky.social/post/3xxxx");
+        assert_eq!(fetched.title, "hello <world>");
+        assert_eq!(fetched.media.len(), 1);
+        assert!(!fetched.sensitive);
+        // display_name absent -> empty fallback
+        assert!(
+            fetched.caption.contains("</a>: hello &lt;world&gt;"),
+            "caption: {}",
+            fetched.caption
+        );
+    }
+
+    #[test]
+    fn from_json_sensitive_labels() {
+        let raw = thread_json(serde_json::json!({
+            "$type": "app.bsky.feed.defs#threadViewPost",
+            "post": {
+                "author": { "handle": "u.bsky.social", "displayName": "U" },
+                "record": { "$type": "app.bsky.feed.post", "text": "x" },
+                "labels": [{ "val": "porn" }]
+            }
+        }));
+        let post = Post::from_json(&raw.to_string(), "3xxxx".into()).unwrap();
+        assert!(post.sensitive);
+    }
+
+    #[test]
+    fn from_json_blocked_and_not_found() {
+        let blocked = thread_json(serde_json::json!({
+            "$type": "app.bsky.feed.defs#blockedPost",
+            "blocked": true
+        }));
+        assert!(matches!(
+            Post::from_json(&blocked.to_string(), "3xxxx".into()),
+            Err(FetchError::Blocked)
+        ));
+
+        let not_found = thread_json(serde_json::json!({
+            "$type": "app.bsky.feed.defs#notFoundPost",
+            "notFound": true
+        }));
+        assert!(matches!(
+            Post::from_json(&not_found.to_string(), "3xxxx".into()),
+            Err(FetchError::NotFound)
+        ));
+    }
+
+    #[tokio::test]
+    async fn live_fetch_with_photos() {
+        let fetched = fetch_from_url(
+            "https://bsky.app/profile/asagi0398.bsky.social/post/3mqkhrq5w6k2m",
+        )
+        .await
+        .unwrap();
+        assert_eq!(
+            fetched.source_url,
+            "https://bsky.app/profile/asagi0398.bsky.social/post/3mqkhrq5w6k2m"
+        );
+        assert!(!fetched.caption.is_empty());
+    }
+
+    #[tokio::test]
+    async fn live_fetch_smoke() {
+        let fetched = fetch_from_url("https://bsky.app/profile/fu-futa.bsky.social/post/3laoveufjv224")
+            .await
+            .unwrap();
+        assert_eq!(
+            fetched.source_url,
+            "https://bsky.app/profile/fu-futa.bsky.social/post/3laoveufjv224"
+        );
+        assert!(!fetched.caption.is_empty());
+    }
+}

crates/x-media/src/site/bsky/mod.rs

@@ -0,0 +1,4 @@
+mod interface;
+mod model;
+
+pub use interface::{PATTERN, Post, enabled, fetch_from_url};

crates/x-media/src/site/bsky/model.rs

@@ -0,0 +1,60 @@
+use serde::Deserialize;
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Info {
+    pub(crate) thread: Thread,
+}
+
+#[derive(Deserialize, Debug)]
+#[serde(tag = "$type")]
+pub(crate) enum Thread {
+    #[serde(rename = "app.bsky.feed.defs#threadViewPost")]
+    Post { post: Post },
+    #[serde(rename = "app.bsky.feed.defs#notFoundPost")]
+    NotFound,
+    #[serde(rename = "app.bsky.feed.defs#blockedPost")]
+    Blocked,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Post {
+    pub(crate) author: Author,
+    pub(crate) record: PostRecord,
+    pub(crate) embed: Option<Media>,
+    #[serde(default)]
+    pub(crate) labels: Vec<Label>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Author {
+    pub(crate) handle: String,
+    #[serde(rename = "displayName", default)]
+    pub(crate) display_name: Option<String>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct PostRecord {
+    pub(crate) text: String,
+}
+
+#[derive(Deserialize, Debug)]
+#[serde(tag = "$type")]
+pub(crate) enum Media {
+    #[serde(rename = "app.bsky.embed.images#view")]
+    Images { images: Vec<Image> },
+    #[serde(rename = "app.bsky.embed.video#view")]
+    Video { playlist: String, thumbnail: String },
+    #[serde(rename = "app.bsky.embed.external#view")]
+    External,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Image {
+    pub(crate) thumb: String,
+    pub(crate) fullsize: String,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Label {
+    pub(crate) val: String,
+}

crates/x-media/src/site/mod.rs

@@ -0,0 +1,242 @@
+//! Site fetching dispatcher and unified result types.
+//!
+//! Dispatch order: twitter → bsky → pixiv. Each site module exports a
+//! `PATTERN`, `enabled()` and `fetch_from_url()`; a future site plugs in by
+//! adding one guarded entry in [`fetch_once`].
+
+use std::fmt;
+use std::sync::LazyLock;
+use std::time::Duration;
+
+pub mod bsky;
+pub mod pixiv;
+pub mod twitter;
+
+pub use pixiv::PixivError;
+
+/// The result of fetching a post: canonical URL, HTML caption, raw text,
+/// media list and spoiler flag. Produced by [`fetch`].
+#[derive(Debug)]
+pub struct Fetched {
+    /// Canonical URL: x.com/{author}/status/{id} |
+    /// https://www.pixiv.net/artworks/{id} |
+    /// https://bsky.app/profile/{handle}/post/{rkey}
+    pub source_url: String,
+    /// The exact HTML produced by the site's caption().
+    pub caption: String,
+    /// Raw post text (tweet text / bsky text / pixiv title).
+    pub title: String,
+    pub media: Vec<crate::media::Media>,
+    /// Spoiler flag for all media of this post.
+    pub sensitive: bool,
+    /// Raw values (pre-escaped) for user-customizable caption formats.
+    pub(crate) render_data: Option<RenderData>,
+    /// Keeps temp files (e.g. an encoded ugoira MP4) alive until the caller
+    /// finishes uploading; not part of the public contract.
+    pub(crate) _keep_alive: Option<tempfile::TempDir>,
+}
+
+/// Pre-escaped values for `{url} {author} {author_url} {title} {tags}`
+/// placeholders in user-supplied caption formats.
+#[derive(Debug)]
+pub(crate) struct RenderData {
+    pub url: String,
+    pub author: String,
+    pub author_url: String,
+    pub title: String,
+    pub tags: String,
+}
+
+impl Fetched {
+    /// The site this post came from (used for per-site format overrides).
+    pub fn site_name(&self) -> &'static str {
+        if self.source_url.contains("x.com") || self.source_url.contains("twitter.com") {
+            "twitter"
+        } else if self.source_url.contains("bsky.app") {
+            "bsky"
+        } else if self.source_url.contains("pixiv.net") {
+            "pixiv"
+        } else {
+            "unknown"
+        }
+    }
+
+    /// Renders a user-supplied caption format. The format string is
+    /// HTML-escaped in full, then the (already-escaped) placeholder values
+    /// are substituted — users can structure text but never inject raw HTML
+    /// or attributes. An empty/unknown format falls back to the built-in
+    /// caption.
+    pub fn caption_with(&self, format: &str) -> String {
+        match (&self.render_data, format.is_empty()) {
+            (Some(data), false) => {
+                let escaped = html_escape::encode_text(format).into_owned();
+                escaped
+                    .replace("{url}", &data.url)
+                    .replace("{author}", &data.author)
+                    .replace("{author_url}", &data.author_url)
+                    .replace("{title}", &data.title)
+                    .replace("{tags}", &data.tags)
+            }
+            _ => self.caption.clone(),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub enum FetchError {
+    Http(reqwest::Error),
+    Json(serde_json::Error),
+    Pixiv(PixivError),
+    NotFound,
+    Blocked,
+}
+
+impl fmt::Display for FetchError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            FetchError::Http(e) => write!(f, "http error: {e}"),
+            FetchError::Json(e) => write!(f, "json error: {e}"),
+            FetchError::Pixiv(e) => write!(f, "pixiv error: {e}"),
+            FetchError::NotFound => write!(f, "not found"),
+            FetchError::Blocked => write!(f, "blocked"),
+        }
+    }
+}
+
+impl std::error::Error for FetchError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            FetchError::Http(e) => Some(e),
+            FetchError::Json(e) => Some(e),
+            FetchError::Pixiv(e) => Some(e),
+            FetchError::NotFound | FetchError::Blocked => None,
+        }
+    }
+}
+
+impl From<reqwest::Error> for FetchError {
+    fn from(e: reqwest::Error) -> Self {
+        FetchError::Http(e)
+    }
+}
+
+
+impl From<serde_json::Error> for FetchError {
+    fn from(e: serde_json::Error) -> Self {
+        FetchError::Json(e)
+    }
+}
+
+impl From<PixivError> for FetchError {
+    fn from(e: PixivError) -> Self {
+        FetchError::Pixiv(e)
+    }
+}
+
+/// Shared HTTP client (browser User-Agent) for twitter/bsky fetches and
+/// [`download_media`].
+pub(crate) static CLIENT: LazyLock<reqwest::Client> = LazyLock::new(|| {
+    let builder = reqwest::Client::builder().user_agent("Mozilla/5.0");
+    // Each `#[tokio::test]` runs on its own runtime; the connection pool is
+    // bound to the runtime that created it, so cross-runtime reuse of idle
+    // connections fails with DispatchGone. In test builds every request uses
+    // a fresh connection. Production runs on one runtime and keeps pooling.
+    #[cfg(test)]
+    let builder = builder.pool_max_idle_per_host(0);
+    builder.build().expect("failed to build HTTP client")
+});
+
+/// Fetches a post from its URL. Returns `Ok(None)` when no site pattern
+/// matches (unsupported links are silently ignored by the bot).
+///
+/// Transient network failures are retried: 3 total attempts with 1s then 2s
+/// delays. Non-Http errors (Json/NotFound/Blocked/Pixiv) are not retried.
+pub async fn fetch(url: &str) -> Result<Option<Fetched>, FetchError> {
+    let mut last_http_error = None;
+    for attempt in 0..3u32 {
+        match fetch_once(url).await {
+            Ok(Some(fetched)) => {
+                log::info!(
+                    "fetched {url}: site {} returned {} media",
+                    fetched.site_name(),
+                    fetched.media.len()
+                );
+                return Ok(Some(fetched));
+            }
+            Ok(None) => return Ok(None),
+            Err(FetchError::Http(e)) => {
+                last_http_error = Some(e);
+                if attempt < 2 {
+                    tokio::time::sleep(Duration::from_secs(1 << attempt)).await;
+                }
+            }
+            Err(other) => return Err(other),
+        }
+    }
+    Err(FetchError::Http(
+        last_http_error.expect("retry loop always ran 3 attempts"),
+    ))
+}
+
+async fn fetch_once(url: &str) -> Result<Option<Fetched>, FetchError> {
+    if twitter::enabled() && twitter::PATTERN.is_match(url) {
+        return Ok(Some(twitter::fetch_from_url(url).await?));
+    }
+    if bsky::enabled() && bsky::PATTERN.is_match(url) {
+        return Ok(Some(bsky::fetch_from_url(url).await?));
+    }
+    if pixiv::enabled() && pixiv::PATTERN.is_match(url) {
+        return Ok(Some(pixiv::fetch_from_url(url).await?));
+    }
+    Ok(None)
+}
+
+/// Downloads media bytes for the bot's upload fallback: when Telegram's own
+/// fetch of a media URL is blocked (hotlink protection), the bot downloads
+/// the file itself and uploads it via multipart. Site-appropriate headers:
+/// pixiv image hosts need the `Referer` header.
+pub async fn download_media(url: &str) -> Result<bytes::Bytes, FetchError> {
+    let mut request = CLIENT.get(url);
+    let lower = url.to_ascii_lowercase();
+    if lower.contains("pximg.net") {
+        request = request.header("Referer", "https://www.pixiv.net/");
+    }
+    let response = request.send().await?;
+    Ok(response.bytes().await?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn unsupported_url_returns_none() {
+        let result = fetch("https://example.com/some/article").await;
+        assert!(matches!(result, Ok(None)), "got {result:?}");
+    }
+
+    #[tokio::test]
+    async fn unknown_scheme_returns_none() {
+        let result = fetch("not a url at all").await;
+        assert!(matches!(result, Ok(None)), "got {result:?}");
+    }
+
+    #[tokio::test]
+    async fn download_media_pixiv_original_with_referer() {
+        // Proves the Referer header is attached for i.pximg.net: a header-less
+        // GET to a pixiv original URL is rejected with 403.
+        if std::env::var("PIXIV_REFRESH_TOKEN").is_err() {
+            eprintln!("skipping: no PIXIV_REFRESH_TOKEN");
+            return;
+        }
+        let illustration = pixiv::fetch(126839080).await.unwrap();
+        let fetched: Fetched = illustration.into();
+        let url = match fetched.media.first() {
+            Some(crate::media::Media::Illustration { url, .. }) => url.clone(),
+            other => panic!("expected illustration media, got {other:?}"),
+        };
+        assert!(url.contains("i.pximg.net"));
+        let bytes = download_media(&url).await.unwrap();
+        assert!(!bytes.is_empty());
+    }
+}

crates/x-media/src/site/pixiv/api.rs

@@ -0,0 +1,394 @@
+//! Native pixiv app-API client (replaces pixiv3-rs).
+//!
+//! Token exchange against `oauth.secure.pixiv.net` and illust detail against
+//! `app-api.pixiv.net`, deserialized with the kept `model.rs` types.
+
+use super::interface::Illustration;
+use super::model::{IllustrationModel, TypeModel, UgoiraMetadataModel};
+use crate::media::Media;
+use crate::site::FetchError;
+use std::env;
+use std::fmt;
+use std::io::{Cursor, Read};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::LazyLock;
+use std::time::{Duration, SystemTime};
+
+const AUTH_TOKEN_URL: &str = "https://oauth.secure.pixiv.net/auth/token";
+const APP_API_URL: &str = "https://app-api.pixiv.net";
+const CLIENT_ID: &str = "MOBrBDS8blbauoSck0ZfDbtuzpyT";
+const CLIENT_SECRET: &str = "lsACyCD94FhDUtGTXi3QzcFE2uU1hqtDaKeqrdwj";
+const AUTH_USER_AGENT: &str = "PixivAndroidApp/5.0.234 (Android 11; Pixel 5)";
+const APP_USER_AGENT: &str = "PixivIOSApp/7.13.3 (iOS 14.6; iPhone13,2)";
+/// Token refresh safe margin (seconds).
+const TOKEN_REFRESH_SAFE_MARGIN: u64 = 300;
+
+#[derive(Debug)]
+pub enum PixivError {
+    /// No refresh token available (PIXIV_REFRESH_TOKEN unset).
+    NoAuth,
+    Http(reqwest::Error),
+    Json(serde_json::Error),
+    Api(String),
+}
+
+impl fmt::Display for PixivError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            PixivError::NoAuth => write!(f, "pixiv: no authentication"),
+            PixivError::Http(e) => write!(f, "pixiv http error: {e}"),
+            PixivError::Json(e) => write!(f, "pixiv json error: {e}"),
+            PixivError::Api(message) => write!(f, "pixiv api error: {message}"),
+        }
+    }
+}
+
+impl std::error::Error for PixivError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            PixivError::Http(e) => Some(e),
+            PixivError::Json(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+impl From<reqwest::Error> for PixivError {
+    fn from(e: reqwest::Error) -> Self {
+        PixivError::Http(e)
+    }
+}
+
+impl From<serde_json::Error> for PixivError {
+    fn from(e: serde_json::Error) -> Self {
+        PixivError::Json(e)
+    }
+}
+
+/// Native pixiv app-API client.
+pub struct PixivAPI {
+    refresh_token: String,
+    access_token: tokio::sync::Mutex<Option<(String, SystemTime)>>,
+}
+
+impl PixivAPI {
+    pub fn new(refresh_token: String) -> Self {
+        Self {
+            refresh_token,
+            access_token: tokio::sync::Mutex::new(None),
+        }
+    }
+
+    /// Returns a valid access token, exchanging the refresh token when none
+    /// is cached or it has expired.
+    pub async fn get_access_token(&self) -> Result<String, PixivError> {
+        let mut guard = self.access_token.lock().await;
+        if let Some((token, expires_at)) = guard.as_ref()
+            && *expires_at > SystemTime::now()
+        {
+            return Ok(token.clone());
+        }
+        let response = crate::site::CLIENT
+            .post(AUTH_TOKEN_URL)
+            .form(&[
+                ("client_id", CLIENT_ID),
+                ("client_secret", CLIENT_SECRET),
+                ("grant_type", "refresh_token"),
+                ("include_policy", "true"),
+                ("refresh_token", &self.refresh_token),
+            ])
+            .header("User-Agent", AUTH_USER_AGENT)
+            .send()
+            .await?;
+        let json: serde_json::Value = serde_json::from_str(&response.text().await?)?;
+        let access_token = json
+            .get("access_token")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| {
+                let message = json
+                    .get("error")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("invalid token response");
+                PixivError::Api(message.to_string())
+            })?
+            .to_string();
+        let expires_in = json
+            .get("expires_in")
+            .and_then(|v| v.as_u64())
+            .filter(|&sec| sec > 0)
+            .unwrap_or(3600);
+        let expires_at = SystemTime::now()
+            + Duration::from_secs(expires_in.saturating_sub(TOKEN_REFRESH_SAFE_MARGIN));
+        *guard = Some((access_token.clone(), expires_at));
+        Ok(access_token)
+    }
+
+    /// Fetches illust detail from the app API.
+    pub async fn illust_detail(&self, illust_id: u64) -> Result<IllustrationModel, PixivError> {
+        let access_token = self.get_access_token().await?;
+        let response = crate::site::CLIENT
+            .get(format!("{APP_API_URL}/v1/illust/detail?illust_id={illust_id}"))
+            .header("app-os", "ios")
+            .header("app-os-version", "14.6")
+            .header("User-Agent", APP_USER_AGENT)
+            .bearer_auth(access_token)
+            .send()
+            .await?;
+        let json: serde_json::Value = serde_json::from_str(&response.text().await?)?;
+        if json.get("error").is_some() {
+            let message = json
+                .get("message")
+                .and_then(|v| v.as_str())
+                .unwrap_or("illust detail failed");
+            return Err(PixivError::Api(message.to_string()));
+        }
+        let illust = json
+            .get("illust")
+            .ok_or_else(|| PixivError::Api("missing illust in response".to_string()))?;
+        Ok(serde_json::from_value(illust.clone())?)
+    }
+
+    pub async fn fetch(&self, illust_id: u64) -> Result<Illustration, FetchError> {
+        let model = self.illust_detail(illust_id).await?;
+        let mut illustration = Illustration::from_model(&model);
+        if matches!(&model.r#type, TypeModel::Ugoira) {
+            // Real ugoira support: download the frame zip and encode an MP4.
+            // Without ffmpeg (or on encode failure) the post stays
+            // unsupported (empty media, like Python).
+            match self.ugoira_video(illust_id).await {
+                Ok(Some((mp4_path, _keep_alive))) => {
+                    illustration.media.push(Media::Video {
+                        title: None,
+                        url: mp4_path,
+                        thumbnail_url: model.image_urls.medium.clone(),
+                    });
+                    illustration._keep_alive = Some(_keep_alive);
+                }
+                Ok(None) => {}
+                Err(e) => log::error!("ugoira encode failed for {illust_id}: {e}"),
+            }
+        }
+        Ok(illustration)
+    }
+
+    /// Fetches ugoira metadata (frame zip + frame delays) from the app API.
+    pub async fn ugoira_metadata(&self, illust_id: u64) -> Result<UgoiraMetadataModel, PixivError> {
+        let access_token = self.get_access_token().await?;
+        let response = crate::site::CLIENT
+            .get(format!("{APP_API_URL}/v1/ugoira/metadata?illust_id={illust_id}"))
+            .header("app-os", "ios")
+            .header("app-os-version", "14.6")
+            .header("User-Agent", APP_USER_AGENT)
+            .bearer_auth(access_token)
+            .send()
+            .await?;
+        let json: serde_json::Value = serde_json::from_str(&response.text().await?)?;
+        if json.get("error").is_some() {
+            let message = json
+                .get("message")
+                .and_then(|v| v.as_str())
+                .unwrap_or("ugoira metadata failed");
+            return Err(PixivError::Api(message.to_string()));
+        }
+        let metadata = json
+            .get("ugoira_metadata")
+            .ok_or_else(|| PixivError::Api("missing ugoira_metadata".to_string()))?;
+        Ok(serde_json::from_value(metadata.clone())?)
+    }
+
+    /// Downloads the frame zip and encodes one MP4 via ffmpeg. Returns the
+    /// MP4 path plus the temp directory that must stay alive until the file
+    /// is uploaded.
+    async fn ugoira_video(
+        &self,
+        illust_id: u64,
+    ) -> Result<Option<(String, tempfile::TempDir)>, PixivError> {
+        if !ffmpeg_available() {
+            log_once_ffmpeg_missing();
+            return Ok(None);
+        }
+        let metadata = self.ugoira_metadata(illust_id).await?;
+        if metadata.frames.is_empty() {
+            return Ok(None);
+        }
+        let zip_url = metadata
+            .zip_url
+            .clone()
+            .or_else(|| metadata.zip_urls.as_ref().map(|z| z.medium.clone()));
+        let Some(zip_url) = zip_url else {
+            return Ok(None);
+        };
+        let zip_bytes = crate::site::download_media(&zip_url).await.map_err(|e| match e {
+            FetchError::Http(e) => PixivError::Http(e),
+            other => PixivError::Api(format!("frame zip download failed: {other}")),
+        })?;
+        let frame_delays = metadata.frames.iter().map(|f| f.delay).collect::<Vec<_>>();
+        let result = tokio::task::spawn_blocking(
+            move || -> Result<(String, tempfile::TempDir), String> {
+            let frames_dir = tempfile::tempdir().map_err(|e| e.to_string())?;
+            let out_dir = tempfile::tempdir().map_err(|e| e.to_string())?;
+
+            // Extract frames to canonical zero-padded names; pixiv ugoira
+            // frames are uniformly jpg or png per artwork.
+            let mut archive = zip::ZipArchive::new(Cursor::new(zip_bytes))
+                .map_err(|e| format!("unzip: {e}"))?;
+            // pixiv ugoira frames are uniformly jpg or png per artwork; take
+            // the extension from the first entry.
+            let extension = if archive.len() > 0 {
+                let first_name = archive
+                    .by_index(0)
+                    .map_err(|e| e.to_string())?
+                    .name()
+                    .to_string();
+                first_name
+                    .rsplit('.')
+                    .next()
+                    .unwrap_or("jpg")
+                    .to_string()
+            } else {
+                "jpg".to_string()
+            };
+            let mut count = 0usize;
+            for i in 0..archive.len() {
+                let mut entry = archive.by_index(i).map_err(|e| e.to_string())?;
+                let mut bytes = Vec::new();
+                entry.read_to_end(&mut bytes).map_err(|e| e.to_string())?;
+                let path = frames_dir.path().join(format!("img_{count:05}.{extension}"));
+                std::fs::write(&path, bytes).map_err(|e| e.to_string())?;
+                count += 1;
+            }
+            if count == 0 {
+                return Err("empty frame zip".to_string());
+            }
+
+            // Constant rate from the median frame delay (ms).
+            let mut delays = frame_delays;
+            delays.sort_unstable();
+            let median = delays[delays.len() / 2].max(1);
+            let framerate = 1000.0 / median as f64;
+
+            let output = out_dir.path().join("ugoira.mp4");
+            let status = std::process::Command::new("ffmpeg")
+                .args([
+                    "-y",
+                    "-framerate",
+                    &framerate.to_string(),
+                    "-i",
+                    &frames_dir.path().join(format!("img_%05d.{extension}")).to_string_lossy(),
+                    // libx264 needs even dimensions; pixiv ugoira frames can
+                    // be odd-sized (e.g. 277x405).
+                    "-vf",
+                    "scale=trunc(iw/2)*2:trunc(ih/2)*2",
+                    "-c:v",
+                    "libx264",
+                    "-pix_fmt",
+                    "yuv420p",
+                    "-movflags",
+                    "+faststart",
+                    &output.to_string_lossy(),
+                ])
+                .stdout(std::process::Stdio::null())
+                .stderr(std::process::Stdio::null())
+                .status()
+                .map_err(|e| format!("ffmpeg spawn failed: {e}"))?;
+            if !status.success() {
+                return Err(format!("ffmpeg exited with {status}"));
+            }
+            Ok((output.to_string_lossy().into_owned(), out_dir))
+        },
+        )
+        .await
+        .expect("ugoira encode worker panicked");
+        match result {
+            Ok(pair) => Ok(Some(pair)),
+            Err(message) => {
+                log::error!("ugoira encode failed for {illust_id}: {message}");
+                Ok(None)
+            }
+        }
+    }
+}
+
+static FFMPEG_AVAILABLE: LazyLock<bool> = LazyLock::new(|| {
+    std::process::Command::new("ffmpeg")
+        .arg("-version")
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+});
+
+static FFMPEG_MISSING_LOGGED: AtomicBool = AtomicBool::new(false);
+
+fn ffmpeg_available() -> bool {
+    *FFMPEG_AVAILABLE
+}
+
+fn log_once_ffmpeg_missing() {
+    if !FFMPEG_MISSING_LOGGED.swap(true, Ordering::Relaxed) {
+        log::warn!("ffmpeg not found; pixiv ugoira posts stay unsupported");
+    }
+}
+
+/// pixiv3-rs replacement: `None` when `PIXIV_REFRESH_TOKEN` is unset.
+static PIXIV_CLIENT: LazyLock<Option<PixivAPI>> = LazyLock::new(|| {
+    env::var("PIXIV_REFRESH_TOKEN").ok().map(PixivAPI::new)
+});
+
+/// Set at startup when the login validation fails; pixiv stays disabled until
+/// the next process start.
+static DISABLED: AtomicBool = AtomicBool::new(false);
+
+pub fn enabled() -> bool {
+    !DISABLED.load(Ordering::Relaxed) && env::var("PIXIV_REFRESH_TOKEN").is_ok()
+}
+
+/// Permanently disables pixiv until the next process start.
+pub fn disable() {
+    DISABLED.store(true, Ordering::Relaxed);
+}
+
+/// Forces the refresh-token → access-token exchange now, surfacing invalid
+/// tokens and network errors. Called once at bot startup; on failure the bot
+/// calls [`disable`].
+pub async fn validate() -> Result<(), PixivError> {
+    match PIXIV_CLIENT.as_ref() {
+        None => Err(PixivError::NoAuth),
+        Some(client) => {
+            client.get_access_token().await?;
+            Ok(())
+        }
+    }
+}
+
+pub async fn fetch(illust_id: u64) -> Result<Illustration, FetchError> {
+    let client = PIXIV_CLIENT
+        .as_ref()
+        .filter(|_| enabled())
+        .ok_or(FetchError::Pixiv(PixivError::NoAuth))?;
+    client.fetch(illust_id).await
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use dotenv::dotenv;
+
+    #[tokio::test]
+    async fn test_fetch() {
+        dotenv().ok();
+        let result = fetch(126839080).await;
+        assert!(result.is_ok());
+        println!("{:#?}", result);
+    }
+
+    #[tokio::test]
+    async fn validate_with_bogus_token_fails() {
+        dotenv().ok();
+        // A bogus token must surface as Api error (invalid_grant), not panic.
+        let client = PixivAPI::new("bogus_token_for_testing".to_string());
+        let result = client.get_access_token().await;
+        assert!(matches!(result, Err(PixivError::Api(_))), "got {result:?}");
+    }
+}

crates/x-media/src/site/pixiv/interface.rs

@@ -0,0 +1,375 @@
+use super::model::{IllustrationModel, TypeModel};
+use crate::media::Media;
+use crate::site::{FetchError, Fetched};
+use html_escape::encode_text;
+use regex::Regex;
+use std::sync::LazyLock;
+
+pub static PATTERN: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new(r"(?:www\.)?pixiv\.net/(?:en/)?(?:(?:i|artworks)/|member_illust\.php\?(?:mode=[a-z_]*&)?illust_id=)(\d+)").unwrap()
+});
+
+pub fn enabled() -> bool {
+    super::api::enabled()
+}
+
+pub async fn fetch_from_url(url: &str) -> Result<Fetched, FetchError> {
+    let id = PATTERN
+        .captures(url)
+        .and_then(|caps| caps.get(1))
+        .map(|m| m.as_str())
+        .ok_or(FetchError::NotFound)?;
+    let id = id.parse::<u64>().map_err(|_| FetchError::NotFound)?;
+    Ok(super::api::fetch(id).await?.into())
+}
+
+#[derive(Debug)]
+pub struct Illustration {
+    id: String,
+    title: String,
+    author: String,
+    author_id: String,
+    tags: Vec<String>,
+    pub(crate) media: Vec<Media>,
+    nsfw: bool,
+    /// Keeps a temp dir (ugoira MP4) alive until the send completes.
+    pub(crate) _keep_alive: Option<tempfile::TempDir>,
+}
+
+impl Illustration {
+    fn url(&self) -> String {
+        format!("https://www.pixiv.net/artworks/{}", self.id)
+    }
+
+    fn author_url(&self) -> String {
+        format!("https://www.pixiv.net/users/{}", self.author_id)
+    }
+
+    pub fn caption(&self) -> String {
+        format!(
+            "<a href=\"{url}\">{title}</a> / <a href=\"{author_url}\">{author}</a>\n{tags}",
+            url = self.url(),
+            title = encode_text(&self.title),
+            author_url = self.author_url(),
+            author = encode_text(&self.author),
+            tags = encode_text(
+                &self
+                    .tags
+                    .iter()
+                    .map(|tag| format!("#{tag}"))
+                    .collect::<Vec<_>>()
+                    .join(" ")
+            ),
+        )
+    }
+
+    pub fn from_model(model: &IllustrationModel) -> Self {
+        let id = model.id.to_string();
+        let title = model.title.clone();
+        let author = model.user.name.clone();
+        let author_id = model.user.id.to_string();
+        let mut tags: Vec<String> = model.tags.iter().map(|tag| tag.name.clone()).collect();
+        // illust_ai_type: 0 = undefined, 1 = not AI, 2 = AI-generated.
+        // Mark AI works with a leading #AI tag (rendered via the `#{tag}`
+        // caption format).
+        if model.illust_ai_type == 2 {
+            tags.insert(0, "AI".to_string());
+        }
+        let mut media = vec![];
+        if matches!(&model.r#type, TypeModel::Ugoira) {
+            // No static images for ugoira; the fetch path encodes an MP4 via
+            // ffmpeg and appends it as a Video item (api.rs). This fallback
+            // keeps media empty when encoding fails or ffmpeg is missing.
+        } else if model.page_count > 1 {
+            media.extend(model.meta_pages.iter().filter_map(|page| {
+                page.image_urls.original.clone().map(|original| Media::Illustration {
+                    title: None,
+                    url: original,
+                    thumbnail_url: Some(page.image_urls.medium.clone()),
+                    fallback_url: Some(page.image_urls.large.clone()),
+                })
+            }));
+        } else if let Some(original) = model
+            .meta_single_page
+            .original_image_url
+            .clone()
+            .or(model.image_urls.original.clone())
+        {
+            media.push(Media::Illustration {
+                title: None,
+                url: original,
+                thumbnail_url: Some(model.image_urls.medium.clone()),
+                fallback_url: Some(model.image_urls.large.clone()),
+            });
+        }
+        let nsfw = model.sanity_level > 5;
+        Self {
+            id,
+            title,
+            author,
+            author_id,
+            tags,
+            media,
+            nsfw,
+            _keep_alive: None,
+        }
+    }
+}
+
+impl From<Illustration> for Fetched {
+    fn from(illustration: Illustration) -> Self {
+        let url = illustration.url();
+        let author_url = illustration.author_url();
+        let tags = illustration
+            .tags
+            .iter()
+            .map(|tag| format!("#{tag}"))
+            .collect::<Vec<_>>()
+            .join(" ");
+        let render_data = Some(crate::site::RenderData {
+            url: url.clone(),
+            author: encode_text(&illustration.author).into_owned(),
+            author_url: author_url.clone(),
+            title: encode_text(&illustration.title).into_owned(),
+            tags: encode_text(&tags).into_owned(),
+        });
+        Fetched {
+            source_url: url,
+            caption: illustration.caption(),
+            title: illustration.title.clone(),
+            media: illustration.media,
+            sensitive: illustration.nsfw,
+            render_data,
+            _keep_alive: illustration._keep_alive,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use super::super::model::IllustrationModel;
+
+    fn illust_json(
+        type_: &str,
+        page_count: u8,
+        single_original: Option<&str>,
+        image_urls_original: Option<&str>,
+        pages: Vec<(Option<&str>, &str, &str)>,
+        ai_type: i32,
+    ) -> serde_json::Value {
+        let meta_pages: Vec<serde_json::Value> = pages
+            .into_iter()
+            .map(|(original, medium, large)| {
+                serde_json::json!({
+                    "image_urls": {
+                        "medium": medium,
+                        "large": large,
+                        "original": original
+                    }
+                })
+            })
+            .collect();
+        serde_json::json!({
+            "illust": {
+                "id": 123,
+                "title": "Art <title>",
+                "type": type_,
+                "image_urls": {
+                    "medium": "medium.jpg",
+                    "large": "large.jpg",
+                    "original": image_urls_original
+                },
+                "user": { "id": 456, "name": "Artist" },
+                "tags": [{ "name": "tag1" }, { "name": "tag2" }],
+                "page_count": page_count,
+                "sanity_level": 6,
+                "illust_ai_type": ai_type,
+                "meta_single_page": { "original_image_url": single_original },
+                "meta_pages": meta_pages
+            }
+        })
+    }
+
+    fn parse(v: serde_json::Value) -> Illustration {
+        let model: IllustrationModel = serde_json::from_value(v["illust"].clone()).unwrap();
+        Illustration::from_model(&model)
+    }
+
+    #[test]
+    fn pattern_matches_all_forms() {
+        let cases = [
+            ("https://www.pixiv.net/artworks/123456", "123456"),
+            ("https://pixiv.net/artworks/123456", "123456"),
+            ("https://www.pixiv.net/en/artworks/123456", "123456"),
+            ("https://www.pixiv.net/i/123456", "123456"),
+            ("https://www.pixiv.net/member_illust.php?mode=medium&illust_id=123456", "123456"),
+            ("https://www.pixiv.net/en/member_illust.php?illust_id=123456", "123456"),
+        ];
+        for (url, id) in cases {
+            let caps = PATTERN.captures(url).unwrap_or_else(|| panic!("{url}"));
+            assert_eq!(caps.get(1).unwrap().as_str(), id);
+        }
+    }
+
+    #[test]
+    fn pattern_rejects_non_artwork_urls() {
+        for url in [
+            "https://www.pixiv.net/users/123",
+            "https://x.com/user/status/123",
+            "https://bsky.app/profile/u/post/3xxxx",
+        ] {
+            assert!(!PATTERN.is_match(url), "{url}");
+        }
+    }
+
+    #[test]
+    fn ugoira_yields_empty_media() {
+        let v = illust_json("ugoira", 1, Some("https://i.pximg.net/orig.jpg"), None, vec![], 0);
+        let illustration = parse(v);
+        let fetched: Fetched = illustration.into();
+        assert!(fetched.media.is_empty());
+        assert!(fetched.sensitive, "sanity_level 6 > 5");
+        assert_eq!(fetched.title, "Art <title>");
+    }
+
+    #[test]
+    fn single_page_with_single_original() {
+        let v = illust_json(
+            "illust",
+            1,
+            Some("https://i.pximg.net/single.jpg"),
+            None,
+            vec![],
+            0,
+        );
+        let fetched: Fetched = parse(v).into();
+        assert_eq!(fetched.media.len(), 1);
+        match &fetched.media[0] {
+            Media::Illustration { url, .. } => {
+                assert_eq!(url, "https://i.pximg.net/single.jpg")
+            }
+            other => panic!("expected Illustration, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn single_page_falls_back_to_image_urls_original() {
+        let v = illust_json(
+            "illust",
+            1,
+            None,
+            Some("https://i.pximg.net/fallback.jpg"),
+            vec![],
+            0,
+        );
+        let fetched: Fetched = parse(v).into();
+        assert_eq!(fetched.media.len(), 1);
+        match &fetched.media[0] {
+            Media::Illustration { url, .. } => {
+                assert_eq!(url, "https://i.pximg.net/fallback.jpg")
+            }
+            other => panic!("expected Illustration, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn single_page_without_any_original_is_empty() {
+        let v = illust_json("illust", 1, None, None, vec![], 0);
+        let fetched: Fetched = parse(v).into();
+        assert!(fetched.media.is_empty());
+    }
+
+    #[test]
+    fn multi_page_skips_pages_without_original() {
+        let v = illust_json(
+            "illust",
+            2,
+            None,
+            None,
+            vec![
+                (None, "m1.jpg", "l1.jpg"),
+                (Some("https://i.pximg.net/p2.jpg"), "m2.jpg", "l2.jpg"),
+            ],
+            0,
+        );
+        let fetched: Fetched = parse(v).into();
+        assert_eq!(fetched.media.len(), 1);
+        match &fetched.media[0] {
+            Media::Illustration { url, thumbnail_url, fallback_url, .. } => {
+                assert_eq!(url, "https://i.pximg.net/p2.jpg");
+                assert_eq!(thumbnail_url.as_deref(), Some("m2.jpg"));
+                assert_eq!(fallback_url.as_deref(), Some("l2.jpg"));
+            }
+            other => panic!("expected Illustration, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn caption_with_escapes_format_and_substitutes() {
+        let v = illust_json("illust", 1, Some("https://i.pximg.net/o.jpg"), None, vec![], 0);
+        let fetched: Fetched = parse(v).into();
+        // Format string is escaped in full, then placeholders substituted.
+        let out = fetched.caption_with("{title} by {author} <script> {tags}");
+        assert!(
+            out.contains("Art &lt;title&gt; by Artist &lt;script&gt; #tag1 #tag2"),
+            "got: {out}"
+        );
+        assert!(!out.contains("<script>"), "no raw HTML injection: {out}");
+        // {url} and {author_url} carry the site's own URLs.
+        let out = fetched.caption_with("{url} {author_url}");
+        assert_eq!(
+            out,
+            "https://www.pixiv.net/artworks/123 https://www.pixiv.net/users/456"
+        );
+        // Empty format falls back to the built-in caption.
+        assert_eq!(fetched.caption_with(""), fetched.caption);
+        assert_eq!(fetched.site_name(), "pixiv");
+    }
+
+    #[test]
+    fn ai_work_gets_leading_ai_tag() {
+        // illust_ai_type == 2 is the only AI marker.
+        let v = illust_json("illust", 1, Some("https://i.pximg.net/o.jpg"), None, vec![], 2);
+        let fetched: Fetched = parse(v).into();
+        assert!(
+            fetched.caption.contains("#AI #tag1 #tag2"),
+            "caption: {}",
+            fetched.caption
+        );
+        // The {tags} placeholder reflects the tag array too.
+        assert!(fetched.caption_with("{tags}").starts_with("#AI "), "got: {}", fetched.caption_with("{tags}"));
+    }
+
+    #[test]
+    fn non_ai_work_has_no_ai_tag() {
+        // 1 = explicitly not AI, 0 = undefined: neither gets the #AI tag.
+        for ai_type in [0, 1] {
+            let v = illust_json("illust", 1, Some("https://i.pximg.net/o.jpg"), None, vec![], ai_type);
+            let fetched: Fetched = parse(v).into();
+            assert!(
+                !fetched.caption.contains("#AI"),
+                "ai_type={ai_type} got: {}",
+                fetched.caption
+            );
+        }
+    }
+
+    #[test]
+    fn caption_escapes_and_links() {
+        let v = illust_json("illust", 1, Some("https://i.pximg.net/o.jpg"), None, vec![], 0);
+        let fetched: Fetched = parse(v).into();
+        assert!(
+            fetched
+                .caption
+                .contains("<a href=\"https://www.pixiv.net/artworks/123\">Art &lt;title&gt;</a>"),
+            "caption: {}",
+            fetched.caption
+        );
+        assert!(fetched.caption.contains("#tag1 #tag2"));
+        assert_eq!(
+            fetched.source_url,
+            "https://www.pixiv.net/artworks/123"
+        );
+    }
+}

crates/x-media/src/site/pixiv/mod.rs

@@ -0,0 +1,6 @@
+mod api;
+mod interface;
+mod model;
+
+pub use api::{PixivAPI, PixivError, disable, fetch, validate};
+pub use interface::{PATTERN, Illustration, enabled, fetch_from_url};

crates/x-media/src/site/pixiv/model.rs

@@ -0,0 +1,79 @@
+// Model set for the native pixiv app-API client (app-api.pixiv.net).
+
+use serde::Deserialize;
+
+#[derive(Deserialize, Debug)]
+pub struct IllustrationModel {
+    pub id: u64,
+    pub title: String,
+    pub r#type: TypeModel,
+    pub image_urls: ImageUrlsModel,
+    pub user: UserInfoModel,
+    pub tags: Vec<IllustrationTagModel>,
+    pub page_count: u8,
+    pub sanity_level: u8,
+    /// 0 = undefined (unlabeled), 1 = not AI, 2 = AI-generated.
+    pub illust_ai_type: i32,
+    pub meta_single_page: MetaSinglePageModel,
+    pub meta_pages: Vec<MetaPageModel>,
+}
+
+#[derive(Deserialize, Debug)]
+pub enum TypeModel {
+    #[serde(rename = "illust")]
+    Illust,
+    #[serde(rename = "manga")]
+    Manga,
+    #[serde(rename = "ugoira")]
+    Ugoira,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct UserInfoModel {
+    pub id: u64,
+    pub name: String,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct ImageUrlsModel {
+    pub medium: String,
+    pub large: String,
+    #[serde(default)]
+    pub original: Option<String>,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct IllustrationTagModel {
+    pub name: String,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct MetaSinglePageModel {
+    #[serde(default)]
+    pub original_image_url: Option<String>,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct MetaPageModel {
+    pub image_urls: ImageUrlsModel,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct UgoiraMetadataModel {
+    /// Older API shape (`zip_url`); newer responses use `zip_urls.medium`.
+    #[serde(default)]
+    pub zip_url: Option<String>,
+    #[serde(default)]
+    pub zip_urls: Option<UgoiraZipUrlsModel>,
+    pub frames: Vec<UgoiraFrameModel>,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct UgoiraZipUrlsModel {
+    pub medium: String,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct UgoiraFrameModel {
+    pub delay: u32,
+}

crates/x-media/src/site/twitter/interface.rs

@@ -0,0 +1,463 @@
+use super::model;
+use crate::media::Media;
+use crate::site::{FetchError, Fetched};
+use html_escape::encode_text;
+use regex::Regex;
+use std::sync::LazyLock;
+
+pub static PATTERN: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new(r"^(?:https?://)?(?:www\.|mobile\.)?(?:x|twitter|fixvx|vxtwitter|fixupx|fxtwitter)\.com/[^.]+/status/(\d+)").unwrap()
+});
+
+pub fn enabled() -> bool {
+    true
+}
+
+pub async fn fetch_from_url(url: &str) -> Result<Fetched, FetchError> {
+    let id = PATTERN
+        .captures(url)
+        .and_then(|caps| caps.get(1))
+        .map(|m| m.as_str())
+        .ok_or(FetchError::NotFound)?;
+    Ok(fetch(id).await?.into())
+}
+
+/// Fetches a tweet from the syndication endpoint. Deleted/blocked tweets
+/// surface as `FetchError::NotFound`.
+pub async fn fetch(id: &str) -> Result<Tweet, FetchError> {
+    let id_num = id.parse::<u64>().map_err(|_| FetchError::NotFound)?;
+    let response = crate::site::CLIENT
+        .get(format!(
+            "https://cdn.syndication.twimg.com/tweet-result?id={id}&lang=en&token={}",
+            syndication_token(id_num)
+        ))
+        .send()
+        .await?;
+    if !response.status().is_success() {
+        return Err(FetchError::NotFound);
+    }
+    let text = response.text().await?;
+    // Deleted tweets answer with {"errors": [...]} instead of a tweet.
+    if serde_json::from_str::<serde_json::Value>(&text)
+        .map(|v| v.get("errors").is_some())
+        .unwrap_or(false)
+    {
+        return Err(FetchError::NotFound);
+    }
+    Ok(Tweet::from_syndication_json(&text).map_err(FetchError::Json)?)
+}
+
+/// The syndication token: JS `((id / 1e15) * PI).toString(36)` (the
+/// `replace('0.','')` is a no-op for realistic tweet ids). The endpoint
+/// currently serves public tweets regardless of the token; the formula is
+/// kept for parity with the known-good client behavior.
+fn syndication_token(id: u64) -> String {
+    let value = (id as f64 / 1e15) * std::f64::consts::PI;
+    let integer = value.trunc() as u64;
+    let mut fraction = value.fract();
+    let mut digits = String::new();
+    if integer == 0 {
+        digits.push('0');
+    } else {
+        let mut n = integer;
+        let mut buf = Vec::new();
+        while n > 0 {
+            buf.push(char::from_digit((n % 36) as u32, 36).unwrap());
+            n /= 36;
+        }
+        digits.extend(buf.into_iter().rev());
+    }
+    digits.push('.');
+    for _ in 0..10 {
+        fraction *= 36.0;
+        let digit = fraction.trunc() as u32;
+        digits.push(char::from_digit(digit.min(35), 36).unwrap());
+        fraction -= digit as f64;
+        if fraction == 0.0 {
+            break;
+        }
+    }
+    digits
+}
+
+#[derive(Debug)]
+pub struct Tweet {
+    id: String,
+    text: String,
+    author: String,
+    author_id: String,
+    media: Vec<Media>,
+    sensitive: bool,
+}
+
+impl Tweet {
+    fn url(&self) -> String {
+        format!("{}/status/{}", self.author_url(), self.id)
+    }
+
+    fn author_url(&self) -> String {
+        format!("https://x.com/{}", self.author_id)
+    }
+
+    pub fn caption(&self) -> String {
+        format!(
+            "{url}\n<a href=\"{author_url}\">{author}</a>: {text}",
+            url = self.url(),
+            author_url = self.author_url(),
+            author = encode_text(&self.author),
+            text = encode_text(&self.text),
+        )
+    }
+
+    pub fn from_syndication_json(raw_json: &str) -> Result<Self, serde_json::Error> {
+        let json: model::SyndicationTweet = serde_json::from_str(raw_json)?;
+        let id = json.id_str;
+        // Strip the appended media short link first, then expand the remaining
+        // t.co short links (the user's own URLs) to their real destinations.
+        let text = expand_links(
+            &strip_trailing_short_links(&json.text, json.display_text_range),
+            &json.entities.urls,
+        );
+        // `name` is the display name, `screen_name` the handle (Python's
+        // vxtwitter mapping: author = display name, author_id = handle).
+        let author = json.user.name;
+        let author_id = json.user.screen_name;
+        let mut media = vec![];
+        for item in json.media_details {
+            match item.media_type.as_str() {
+                "photo" => media.push(Media::Illustration {
+                    title: None,
+                    url: item.media_url_https,
+                    thumbnail_url: None,
+                    fallback_url: None,
+                }),
+                "video" => media.push(Media::Video {
+                    title: None,
+                    url: mp4_variant(&item),
+                    thumbnail_url: item.media_url_https,
+                }),
+                "animated_gif" => media.push(Media::Animated {
+                    title: None,
+                    url: mp4_variant(&item),
+                    thumbnail_url: item.media_url_https,
+                }),
+                _ => {}
+            }
+        }
+        let sensitive = json.possibly_sensitive.unwrap_or(false);
+        Ok(Self {
+            id,
+            text,
+            author,
+            author_id,
+            media,
+            sensitive,
+        })
+    }
+}
+
+/// The raw syndication `text` ends with the appended media short link
+/// (" https://t.co/wmI8McgXul"). `display_text_range` (UTF-16 indices) marks
+/// the visible text; a regex strips any remaining trailing t.co link when the
+/// range is absent or a tweet ends in a URL short link.
+fn strip_trailing_short_links(text: &str, display_text_range: Option<[usize; 2]>) -> String {
+    let mut out = match display_text_range {
+        Some([start, end]) if start < end => {
+            let units: Vec<u16> = text
+                .encode_utf16()
+                .skip(start)
+                .take(end - start)
+                .collect();
+            // Drop the replacement char that a surrogate cut at the boundary
+            // would produce (the range end is a valid UTF-16 boundary in
+            // practice, so this is just a safety net).
+            String::from_utf16_lossy(&units).replace('\u{FFFD}', "")
+        }
+        _ => text.to_string(),
+    };
+    while TRAILING_TCO.is_match(&out) {
+        out = TRAILING_TCO.replace(&out, "").into_owned();
+    }
+    out
+}
+
+/// Trailing Twitter short link, optionally preceded by whitespace.
+static TRAILING_TCO: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new(r"\s*https?://t\.co/[A-Za-z0-9]+$").unwrap()
+});
+
+/// Replaces every t.co short link that has an entity mapping with its
+/// expanded URL. Short links without a mapping stay untouched.
+fn expand_links(text: &str, urls: &[model::SyndicationEntityUrl]) -> String {
+    let mut out = text.to_string();
+    for entity in urls {
+        if let Some(expanded) = &entity.expanded_url {
+            out = out.replace(&entity.url, expanded);
+        }
+    }
+    out
+}
+
+fn mp4_variant(item: &model::SyndicationMedia) -> String {
+    item.video_info
+        .as_ref()
+        .and_then(|info| {
+            info.variants
+                .iter()
+                .find(|variant| variant.content_type == "video/mp4")
+        })
+        .map(|variant| variant.url.clone())
+        .unwrap_or_else(|| item.media_url_https.clone())
+}
+
+impl From<Tweet> for Fetched {
+    fn from(tweet: Tweet) -> Self {
+        let url = tweet.url();
+        let author_url = tweet.author_url();
+        let render_data = Some(crate::site::RenderData {
+            url: url.clone(),
+            author: encode_text(&tweet.author).into_owned(),
+            author_url: author_url.clone(),
+            title: encode_text(&tweet.text).into_owned(),
+            tags: String::new(),
+        });
+        Fetched {
+            source_url: url,
+            caption: tweet.caption(),
+            title: tweet.text.clone(),
+            media: tweet.media,
+            sensitive: tweet.sensitive,
+            render_data,
+            _keep_alive: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fixture(media_details: serde_json::Value) -> serde_json::Value {
+        serde_json::json!({
+            "__typename": "Tweet",
+            "id_str": "861627479294746624",
+            "text": "a & b <c>",
+            "user": { "name": "Display Name", "screen_name": "author_handle" },
+            "possibly_sensitive": true,
+            "mediaDetails": media_details
+        })
+    }
+
+    #[test]
+    fn pattern_matches_all_domains() {
+        for url in [
+            "https://x.com/user/status/1234567890",
+            "https://twitter.com/user/status/1234567890",
+            "https://mobile.twitter.com/user/status/1234567890",
+            "https://www.x.com/user/status/1234567890",
+            "https://fxtwitter.com/user/status/1234567890",
+            "https://fixupx.com/user/status/1234567890",
+            "https://fixvx.com/user/status/1234567890",
+            "https://vxtwitter.com/user/status/1234567890",
+        ] {
+            let caps = PATTERN.captures(url).unwrap_or_else(|| panic!("{url}"));
+            assert_eq!(caps.get(1).unwrap().as_str(), "1234567890");
+        }
+    }
+
+    #[test]
+    fn pattern_rejects_non_tweet_urls() {
+        for url in [
+            "https://x.com/user",
+            "https://x.com/user/status/abc",
+            "https://bsky.app/profile/u/post/3xxxx",
+            "https://pixiv.net/artworks/123",
+            "https://example.com/x.com/user/status/123",
+        ] {
+            assert!(!PATTERN.is_match(url), "{url}");
+        }
+    }
+
+    #[test]
+    fn syndication_json_converts_to_fetched() {
+        let raw = fixture(serde_json::json!([
+            { "type": "photo", "media_url_https": "https://pbs.twimg.com/media/photo.jpg" },
+            {
+                "type": "video",
+                "media_url_https": "https://pbs.twimg.com/thumb.jpg",
+                "video_info": {
+                    "variants": [
+                        { "content_type": "application/x-mpegURL", "url": "https://x.com/pl.m3u8" },
+                        { "content_type": "video/mp4", "url": "https://video.twimg.com/v.mp4" }
+                    ]
+                }
+            }
+        ]));
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let fetched: Fetched = tweet.into();
+        assert_eq!(
+            fetched.source_url,
+            "https://x.com/author_handle/status/861627479294746624"
+        );
+        assert_eq!(fetched.title, "a & b <c>");
+        assert!(fetched.sensitive);
+        assert_eq!(fetched.media.len(), 2);
+        match &fetched.media[1] {
+            Media::Video { url, thumbnail_url, .. } => {
+                assert_eq!(url, "https://video.twimg.com/v.mp4");
+                assert_eq!(thumbnail_url, "https://pbs.twimg.com/thumb.jpg");
+            }
+            other => panic!("expected video, got {other:?}"),
+        }
+        assert!(
+            fetched
+                .caption
+                .contains("<a href=\"https://x.com/author_handle\">Display Name</a>: a &amp; b &lt;c&gt;"),
+            "caption: {}",
+            fetched.caption
+        );
+    }
+
+    #[test]
+    fn syndication_text_only_has_no_media() {
+        let raw = fixture(serde_json::json!([]));
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let fetched: Fetched = tweet.into();
+        assert!(fetched.media.is_empty());
+    }
+
+    #[test]
+    fn syndication_gif_maps_to_animated() {
+        let raw = fixture(serde_json::json!([
+            {
+                "type": "animated_gif",
+                "media_url_https": "https://pbs.twimg.com/g.jpg",
+                "video_info": {
+                    "variants": [{ "content_type": "video/mp4", "url": "https://video.twimg.com/g.mp4" }]
+                }
+            }
+        ]));
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        assert!(matches!(&tweet.media[0], Media::Animated { .. }));
+    }
+
+    #[test]
+    fn syndication_text_strips_trailing_media_short_link() {
+        // Real syndication shape: the media short link sits after the visible
+        // text, and display_text_range marks where it begins.
+        let raw = serde_json::json!({
+            "__typename": "Tweet",
+            "id_str": "1",
+            "text": "hello world https://t.co/abc123",
+            "display_text_range": [0, 11],
+            "user": { "name": "N", "screen_name": "h" },
+            "mediaDetails": []
+        });
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        assert_eq!(tweet.text, "hello world");
+        assert!(!tweet.caption().contains("t.co"));
+    }
+
+    #[test]
+    fn syndication_text_strips_trailing_short_link_without_range() {
+        // No display_text_range: the regex fallback removes the trailing link.
+        let raw = serde_json::json!({
+            "__typename": "Tweet",
+            "id_str": "1",
+            "text": "hello https://t.co/abc123",
+            "user": { "name": "N", "screen_name": "h" },
+            "mediaDetails": []
+        });
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        assert_eq!(tweet.text, "hello");
+    }
+
+    #[test]
+    fn syndication_text_expands_url_entities() {
+        // Real FloodSocial shape: the user's own link is a t.co short link in
+        // the text; the entity mapping expands it, the trailing media short
+        // link is stripped.
+        let raw = serde_json::json!({
+            "__typename": "Tweet",
+            "id_str": "1",
+            "text": "Test Tweet with @mentionThis $twtr https://t.co/RzmrQ6wAzD #hashtag https://t.co/9r69akA484",
+            "display_text_range": [0, 67],
+            "user": { "name": "N", "screen_name": "h" },
+            "entities": {
+                "urls": [{
+                    "url": "https://t.co/RzmrQ6wAzD",
+                    "expanded_url": "http://bit.ly/2pUk4be",
+                    "display_url": "bit.ly/2pUk4be"
+                }]
+            },
+            "mediaDetails": []
+        });
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        assert_eq!(
+            tweet.text,
+            "Test Tweet with @mentionThis $twtr http://bit.ly/2pUk4be #hashtag"
+        );
+        assert!(!tweet.caption().contains("t.co"));
+    }
+
+    #[test]
+    fn syndication_text_keeps_unmapped_short_links() {
+        // No entity mapping for the embedded link: it stays as-is. Only the
+        // trailing media link is stripped.
+        let raw = serde_json::json!({
+            "__typename": "Tweet",
+            "id_str": "1",
+            "text": "check https://t.co/abc123 #tag https://t.co/def456",
+            "display_text_range": [0, 30],
+            "user": { "name": "N", "screen_name": "h" },
+            "mediaDetails": []
+        });
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        assert_eq!(tweet.text, "check https://t.co/abc123 #tag");
+    }
+
+    #[test]
+    fn syndication_text_utf16_display_range_keeps_multibyte() {
+        // display_text_range is in UTF-16 units; a Japanese text must not be
+        // sliced by UTF-8 bytes.
+        let text = "コミティア落ちたので、明日は行きません。🙏ごめんなさい";
+        let units: Vec<u16> = text.encode_utf16().collect();
+        assert_eq!(units.len(), 28);
+        let raw = serde_json::json!({
+            "__typename": "Tweet",
+            "id_str": "1",
+            "text": text,
+            "display_text_range": [0, 28],
+            "user": { "name": "N", "screen_name": "h" },
+            "mediaDetails": []
+        });
+        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        assert_eq!(tweet.text, text, "full text kept intact");
+    }
+
+    #[test]
+    fn syndication_token_matches_js_formula() {
+        // JS: ((861627479294746624 / 1e15) * PI).toString(36) == "236.vrsocvda"
+        let token = syndication_token(861627479294746624);
+        assert!(token.starts_with("236.v"), "got {token}");
+    }
+
+    #[tokio::test]
+    async fn live_fetch_with_photos() {
+        let fetched = fetch("861627479294746624").await.unwrap();
+        assert_eq!(fetched.media.len(), 4);
+    }
+
+    #[tokio::test]
+    async fn live_fetch_text_only() {
+        let fetched = fetch("1992471125734142256").await.unwrap();
+        assert!(fetched.media.is_empty());
+    }
+
+    #[tokio::test]
+    async fn live_fetch_deleted_tweet_is_not_found() {
+        // Deleted tweet: the syndication endpoint answers with errors.
+        let result = fetch("0").await;
+        assert!(matches!(result, Err(FetchError::NotFound)), "got {result:?}");
+    }
+}

crates/x-media/src/site/twitter/mod.rs

@@ -0,0 +1,4 @@
+mod interface;
+mod model;
+
+pub use interface::{PATTERN, Tweet, enabled, fetch_from_url};

crates/x-media/src/site/twitter/model.rs

@@ -0,0 +1,62 @@
+use serde::Deserialize;
+
+/// Response shape of the syndication endpoint
+/// (`cdn.syndication.twimg.com/tweet-result`).
+#[derive(Deserialize, Debug)]
+pub struct SyndicationTweet {
+    pub id_str: String,
+    pub text: String,
+    pub user: SyndicationUser,
+    #[serde(default)]
+    pub possibly_sensitive: Option<bool>,
+    /// Visible-text span; the raw `text` field has the appended media short
+    /// link after it. Indices are UTF-16 code units.
+    #[serde(default, rename = "display_text_range")]
+    pub display_text_range: Option<[usize; 2]>,
+    #[serde(default)]
+    pub entities: SyndicationEntities,
+    #[serde(default, rename = "mediaDetails")]
+    pub media_details: Vec<SyndicationMedia>,
+}
+
+#[derive(Deserialize, Debug, Default)]
+pub struct SyndicationEntities {
+    #[serde(default)]
+    pub urls: Vec<SyndicationEntityUrl>,
+}
+
+/// A URL entity: `url` is the t.co short link as it appears in the text,
+/// `expanded_url` the real destination.
+#[derive(Deserialize, Debug)]
+pub struct SyndicationEntityUrl {
+    pub url: String,
+    #[serde(default)]
+    pub expanded_url: Option<String>,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct SyndicationUser {
+    pub name: String,
+    pub screen_name: String,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct SyndicationMedia {
+    #[serde(rename = "type")]
+    pub media_type: String,
+    pub media_url_https: String,
+    #[serde(default)]
+    pub video_info: Option<SyndicationVideoInfo>,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct SyndicationVideoInfo {
+    #[serde(default)]
+    pub variants: Vec<SyndicationVariant>,
+}
+
+#[derive(Deserialize, Debug)]
+pub struct SyndicationVariant {
+    pub content_type: String,
+    pub url: String,
+}