ClassyGitShadowzzh

index.ts

index.ts
// 由 backend `cargo run --bin export_types` 產生 — 勿手改

// This file has been generated by Specta. Do not edit this file manually.
/**  `GET /api/admin/categories`(requireAdmin)。裸陣列。admin 版含 created_at、且 JOIN 不過濾 status。 */
export type AdminCategoryRow = {
	id: number,
	name: string,
	slug: string,
	description: string | null,
	short_description: string | null,
	created_at: string,
	updated_at: string | null,
	post_count: number,
	/**  顯示用譯名(name 仍是資料鍵)。後台編輯用。 */
	name_en: string | null,
	name_ja: string | null,
	name_ko: string | null,
	name_zh_cn: string | null,
	description_en: string | null,
	description_ja: string | null,
	description_ko: string | null,
	description_zh_cn: string | null,
	short_description_en: string | null,
	short_description_ja: string | null,
	short_description_ko: string | null,
	short_description_zh_cn: string | null,
};

export type AdminCollectionResponse = {
	watch: AdminWatchItem[],
	tracks: AdminTrackItem[],
	/**  Spotify 抓失敗的話是理由(沒接 Spotify 不算失敗,tracks 就是空的) */
	tracks_error: string | null,
	hidden: HiddenItem[],
};

/**
 *  admin 留言列的一列:comments 表全欄(DB 宣告序)+ LEFT JOIN 的 post_title。
 *  欄位序對齊舊 `row_to_json`(`SELECT c.*` → comments 宣告序,post_title 附在最後)。
 */
export type AdminCommentRow = {
	id: number,
	post_id: number | null,
	author: string,
	content: string,
	likes: number,
	created_at: string,
	is_admin: number,
	email: string | null,
	website: string | null,
	status: string | null,
	ip: string | null,
	parent_id: number | null,
	avatar_url: string | null,
	thought_id: number | null,
	post_title: string | null,
};

export type AdminCommentsResponse = {
	comments: AdminCommentRow[],
	total: number,
	page: number,
	limit: number,
	counts: CommentCounts,
};

/**  後台的一列(申請者的 IP 不給前端) */
export type AdminFriendRow = {
	id: number,
	slug: string | null,
	name: string,
	url: string,
	description: string,
	feed_url: string | null,
	email: string | null,
	message: string | null,
	/**  pending | waiting | approved | rejected */
	status: string,
	/**  最近一次自動檢查;還沒檢查過是空陣列 */
	checks: FriendCheck[],
	checked_at: string | null,
	sort_order: number,
	created_at: string,
	reviewed_at: string | null,
};

export type AdminFriendsResponse = {
	friends: AdminFriendRow[],
	counts: FriendCounts,
};

/**  後台的一張:疊過的照片,加上原本的檔名(標題改過也看得到是哪個檔)與兩個開關 */
export type AdminPhoto = {
	/**  manifest 上的標題(同步時是檔名) */
	original_title: string,
	/**  精選:前台地面站排在最上面 */
	featured: boolean,
	/**  前台不顯示 */
	hidden: boolean,
} & GalleryPhoto;

export type AdminPhotosResponse = {
	/**  上次同步 NAS 的時間(manifest 的 generatedAt) */
	generatedAt: string,
	photos: AdminPhoto[],
};

/**
 *  `GET /api/admin/posts/:id` 成功回應:`{message, ...row, tags, available_locales}`。
 *  flatten 讓 row 的欄位攤平在頂層,key 序 = message → AdminPostFull 欄位序 → available_locales。
 */
export type AdminPostDetailResponse = {
	message: string,
	available_locales: string[],
} & AdminPostFull;

/**
 *  admin 端點的整列 post(`SELECT p.*` 全欄,含 12 個 i18n 欄)。
 * 
 *  **欄位序 = posts 表宣告序 + tags**,對齊舊 `row_to_json` 的 key 序(serde_json
 *  preserve_order → struct 欄位序即 JSON key 序)。`/api/admin/posts` 與
 *  `/api/admin/posts/:id` 共用;兩者對 excerpt / source_language 的處理不同,由呼叫端覆寫。
 */
export type AdminPostFull = {
	id: number,
	/**  網址用的英文 slug(canonical)。 */
	slug: string | null,
	title: string,
	content: string,
	excerpt: string | null,
	category: string | null,
	status: string,
	author: string | null,
	view_count: number,
	likes: number,
	created_at: string,
	updated_at: string | null,
	layout_type: string | null,
	excerpt_zh_cn: string | null,
	title_ja: string | null,
	content_ja: string | null,
	excerpt_ja: string | null,
	title_en: string | null,
	content_en: string | null,
	excerpt_en: string | null,
	source_language: string | null,
	title_zh_cn: string | null,
	content_zh_cn: string | null,
	series_name: string | null,
	series_order: number | null,
	title_ko: string | null,
	content_ko: string | null,
	allow_comments: boolean,
	excerpt_ko: string | null,
	/**  內容格式:'markdown'(預設)| 'mdx'。 */
	format: string | null,
	/**  摘要裡連到章節的句子,依語系分開(沒有就是空物件)。 */
	excerpt_links: { [key in string]: ExcerptLink[] },
	/**  排程發佈的時間(UTC,`YYYY-MM-DD HH:MM:SS`);只有 status = 'scheduled' 才有值 */
	publish_at: string | null,
	/**  排程時勾了「發佈時推送電子報」,翻成 published 那一刻才寄 */
	newsletter_pending: boolean,
	/**  丟進回收的時間(UTC);30 天後自動刪掉 */
	trashed_at: string | null,
	/**  丟進回收之前的狀態(還原時回到這裡) */
	trashed_from: string | null,
	tags: string[],
};

export type AdminPostsResponse = {
	posts: AdminPostFull[],
	totalPages: number,
	currentPage: number,
	total: number,
};

/**  `GET /api/admin/tags` 單列(admin 版:含 0 篇的 tag、依名排序)。 */
export type AdminTagRow = {
	id: number,
	name: string,
	created_at: string,
	post_count: number,
	/**  顯示用譯名(name 仍是資料鍵)。後台編輯用。 */
	name_en: string | null,
	name_ja: string | null,
	name_ko: string | null,
	name_zh_cn: string | null,
};

/**  後台「在聽」的一首(Spotify 最近播放,含不公開的) */
export type AdminTrackItem = {
	id: string,
	name: string,
	artists: string,
	cover: string | null,
	played_at: string,
	hidden: boolean,
};

/**  `GET /api/admin/users`(**requireOwner**)。`{ users: [...] }`,顯式欄位。 */
export type AdminUserRow = {
	id: number,
	provider: string | null,
	provider_id: string | null,
	display_name: string | null,
	email: string | null,
	avatar_url: string | null,
	role: string | null,
	linked_to: number | null,
	created_at: string | null,
	updated_at: string | null,
};

export type AdminUsersResponse = {
	users: AdminUserRow[],
};

/**  後台「在看」的一部(動畫、電影、影集混在一起,照最後看的時間排) */
export type AdminWatchItem = {
	/**  anime | film | tv */
	kind: string,
	/**  不公開清單用的 key:動畫是 anime_sn、電影是 film_history.id、影集是劇名 */
	key: string,
	title: string,
	cover: string | null,
	/**  動畫是最後一集、影集是看了幾集、電影是評分 */
	detail: string | null,
	watched_at: string | null,
	/**  bahamut | simkl | trakt … */
	source: string | null,
	tmdb_id: number | null,
	hidden: boolean,
	/**  在最愛裡的話是那一筆的 id */
	favorite_id: number | null,
};

/**  走勢圖的一格。`date` 是那一格的起點(`yyyy-MM-dd`,週粒度時是那週的第一天) */
export type AnalyticsPoint = {
	date: string,
	visitors: number,
	pageviews: number,
};

export type AnalyticsResponse = {
	/**  後端有沒有設 `PLAUSIBLE_API_KEY`;沒設時其他欄位都是空的 */
	configured: boolean,
	period: string,
	/**  最近五分鐘的訪客(Plausible 的 realtime);查不到時是 null,不影響其他欄位 */
	realtime: number | null,
	totals: AnalyticsTotals,
	series: AnalyticsPoint[],
	pages: AnalyticsRow[],
	sources: AnalyticsRow[],
	/**  國家是 ISO 3166-1 alpha-2 國碼,前端用 `Intl.DisplayNames` 翻成中文 */
	countries: AnalyticsRow[],
	devices: AnalyticsRow[],
	/**  「在 Plausible 打開」的連結 */
	dashboard_url: string,
};

/**  排行表的一列:名字(頁面路徑、來源、國碼、裝置)與訪客數 */
export type AnalyticsRow = {
	name: string,
	visitors: number,
};

export type AnalyticsTotals = {
	visitors: number,
	visits: number,
	pageviews: number,
	/**  跳出率,百分比(0–100) */
	bounce_rate: number | null,
	/**  平均停留,秒 */
	visit_duration: number | null,
};

export type AnimeHistoryResponse = {
	message: string,
	history: AnimeRow[],
};

/**  `GET /api/anime/history` 一列。 */
export type AnimeRow = {
	anime_sn: number,
	video_sn: number,
	title: string | null,
	cover_url: string | null,
	episode: string | null,
	tmdb_id: number | null,
	last_watched_at: string | null,
};

export type AudioFeature = {
	id: string,
	energy: number,
	danceability: number,
	valence: number,
};

/**  `GET /api/spotify/audio-features`。順序對齊請求的 ids;查不到的位置是 null。 */
export type AudioFeaturesResponse = {
	audio_features: (AudioFeature | null)[],
};

/**  `GET /api/auth/providers` 回應。兩個 provider 一律都在,用 enabled 區分。 */
export type AuthProvidersResponse = {
	google: OAuthProviderInfo,
	github: OAuthProviderInfo,
};

export type BlacklistResponse = {
	blacklist: BlacklistRow[],
};

/**  `GET /api/admin/blacklist`(requireAdmin)。`{ blacklist: rows }`(SELECT *;目前空表)。 */
export type BlacklistRow = {
	id: number,
	ip: string,
	reason: string | null,
	created_at: string,
};

export type BookDetailResponse = {
	message: string,
	book: BookRow,
};

/**  books 一列(`SELECT *`)。欄位序 = books 表宣告序,對齊舊 `row_to_json` 的 key 序。 */
export type BookRow = {
	id: number,
	isbn: string | null,
	title: string,
	authors: string | null,
	publisher: string | null,
	published_date: string | null,
	description: string | null,
	cover_url: string | null,
	page_count: number | null,
	language: string | null,
	categories: string | null,
	reading_status: string | null,
	rating: number | null,
	personal_notes: string | null,
	date_added: string | null,
	date_updated: string | null,
	date_started: string | null,
	date_finished: string | null,
};

export type BooksListResponse = {
	message: string,
	books: BookRow[],
};

export type CategoriesResponse = {
	message: string,
	categories: CategoryRow[],
};

/**  `POST /api/admin/categories` 的 200 回應。 */
export type CategoryCreated = {
	id: number,
	name: string,
	slug: string,
	description: string,
	short_description: string,
	post_count: number,
};

/**
 *  `DELETE /api/admin/categories/{id}` 的 200 回應。
 *  分類被刪時底下的文章會被移到未分類,所以要回報影響了幾篇。
 */
export type CategoryDeleted = {
	message: string,
	affectedPosts: number,
};

/**  `GET /api/categories` 單列。欄位順序對齊 Express SELECT。 */
export type CategoryRow = {
	id: number,
	name: string,
	slug: string,
	description: string | null,
	short_description: string | null,
	updated_at: string | null,
	post_count: number,
	/**  顯示用譯名(name 仍是資料鍵)。沒填就由前端 fallback 回 name。 */
	name_en: string | null,
	name_ja: string | null,
	name_ko: string | null,
	name_zh_cn: string | null,
	/**  描述的譯文(tooltip 用)。 */
	description_en: string | null,
	description_ja: string | null,
	description_ko: string | null,
	description_zh_cn: string | null,
	short_description_en: string | null,
	short_description_ja: string | null,
	short_description_ko: string | null,
	short_description_zh_cn: string | null,
};

/**  `PUT /api/admin/categories/{id}` 的 200 回應(`id` 同樣來自 Path,理由見 [`TagUpdated`])。 */
export type CategoryUpdated = {
	id: number,
	name: string,
	slug: string,
	description: string,
	updated: number,
};

/**
 *  全站留言的狀態計數(**不受 status/search/post_id 過濾影響**,永遠是全域分佈)。
 *  status 受限於這四種(見 comments.rs 建立邏輯 + admin 審核端點),故可 typed 成固定欄位。
 */
export type CommentCounts = {
	pending: number,
	approved: number,
	spam: number,
	trash: number,
};

/**
 *  公開的留言一列(文章與碎念共用)。**不含留言者的 email 與 IP**:這是公開端點,
 *  那兩欄只給後台(`admin::AdminCommentRow`)。欄位順序對齊 live 表 `SELECT *` 的展開順序(少了那兩欄)。
 */
export type CommentRow = {
	id: number,
	post_id: number | null,
	author: string,
	content: string,
	likes: number,
	created_at: string,
	is_admin: number,
	website: string | null,
	status: string | null,
	parent_id: number | null,
	avatar_url: string | null,
	thought_id: number | null,
};

export type CommentsResponse = {
	message: string,
	comments: CommentRow[],
};

export type CountResponse = {
	count: number,
};

/**  建立成功、只需要回新資源 id 的端點。 */
export type CreatedResponse = {
	message: string,
	id: number,
};

/**
 *  `GET /api/quote/daily` 的 quote。text/from 兩個來源都是字串:
 *  外部來源走 fetch_quote → Option<(String, String)>,失敗時走 fallback_pool
 *  的 &'static [(&str, &str)]。前端手寫版把 from 標成可選,實際上一定有值。
 */
export type DailyQuote = {
	text: string,
	from: string,
};

/**  `GET /api/quote/daily` */
export type DailyQuoteResponse = {
	message: string,
	quote: DailyQuote,
};

export type DigestComment = {
	id: number,
	author: string,
	content: string,
	created_at: string,
	post_id: number | null,
	thought_id: number | null,
	post_title: string | null,
	/**
	 *  前端用來組 canonical 網址(`/blog/<slug>`)。少了它只能連到 `/blog/<id>`,
	 *  那得多走一次 301。
	 */
	post_slug: string | null,
};

export type DigestPost = {
	id: number,
	slug: string | null,
	title: string,
	category: string | null,
	created_at: string,
};

export type DigestResponse = {
	message: string,
	posts: DigestPost[],
	thoughts: DigestThought[],
	comments: DigestComment[],
	timeline: DigestTimeline[],
};

export type DigestThought = {
	id: number,
	content: string,
	ref_type: string | null,
	created_at: string,
};

export type DigestTimeline = {
	id: number,
	slug: string | null,
	title: string,
	created_at: string,
};

/**  4xx 的統一形狀。 */
export type ErrorResponse = {
	error: string,
};

/**  摘要裡的一句話,連到 `to` 那一章(`05` 是第五個大節,`05.4` 是它底下第四個小節)。 */
export type ExcerptLink = {
	text: string,
	to: string,
};

/**
 *  EXIF 的數值欄位在同一份 manifest 裡真的有兩種形狀:舊的 Node builder
 *  (`scripts/builder`)寫 exiftool 的格式化字串(`"f/1.4"`、`"1/640"`、`"32 mm"`),
 *  本檔的 `extract_exif` 寫數字。線上 247 張裡兩種混雜,所以型別得誠實地兩者皆可
 *  ——不是為了寬鬆,是資料真的長這樣。
 */
export type ExifValue = number | string;

/**  `GET /api/films/recent` 一列。 */
export type FilmRow = {
	id: number,
	title: string,
	watched_date: string | null,
	rating: number | null,
	source: string | null,
	tmdb_id: number | null,
	poster_url: string | null,
	backdrop_url: string | null,
	release_year: number | null,
	genres: string | null,
};

export type FilmsResponse = {
	message: string,
	films: FilmRow[],
};

/**  一項自動檢查的結果 */
export type FriendCheck = {
	/**  reachable | https | feed | recent | backlink */
	key: string,
	label: string,
	ok: boolean,
	detail: string,
};

export type FriendCounts = {
	pending: number,
	waiting: number,
	approved: number,
	rejected: number,
};

/**  一篇文章 */
export type FriendPost = {
	title: string,
	url: string | null,
	/**  feed 上寫的日期,原樣(RSS 是 RFC 2822、Atom 是 ISO 8601,前端的 Date 兩種都吃) */
	date: string | null,
};

/**  `GET /api/friends` 的一筆 */
export type FriendStar = {
	id: string,
	name: string,
	url: string,
	desc: string,
	/**  有沒有 feed(沒有的是一顆安靜的星) */
	has_feed: boolean,
	/**  最近幾篇,照 feed 上的順序(新的在前);最多 `POSTS_MAX` 篇 */
	posts: FriendPost[],
};

/**  manifest 裡的一張照片。 */
export type GalleryPhoto = {
	id: string,
	title: string,
	description?: string,
	urls: PhotoUrls,
	originalUrl: string,
	thumbnailUrl: string,
	width: number,
	height: number,
	aspectRatio: number,
	size: number,
	format: string,
	/**  舊 builder 產的漸進式佔位圖;本檔不產,但讀到要留著(線上 247 張裡 246 張有) */
	thumbHash: string | null,
	exif: PhotoExif | null,
	/**  epoch 毫秒。舊資料是 EXIF 拍攝時間,缺時退成來源檔 mtime */
	shootTime: number | null,
	tags?: string[],
	tagsEn?: string[],
	gps: PhotoGps | null,
};

/**
 *  `GET /api/gallery/photos` 的回應:manifest,加上站長標的精選(照片 id)。
 *  精選不放進每張照片裡:照片的形狀就是 manifest 檔的形狀,那個檔每次同步都會重寫,
 *  不該因為一個只有讀的時候才有的值而多出欄位。
 */
export type GalleryPhotosResponse = {
	/**  精選的照片 id,前台地面站排在最上面 */
	featured: string[],
} & PhotosManifest;

/**
 *  PushEvent 的一個 commit。sha 缺的 commit 直接不收——沒有 sha 就連不出 commit 連結,
 *  收進來只是把「可能是 null」傳染給前端。
 */
export type GithubCommit = {
	sha: string,
	message: string,
	author: GithubCommitAuthor | null,
};

export type GithubCommitAuthor = {
	name: string | null,
	email: string | null,
};

/**  貢獻熱圖的一天。 */
export type GithubContributionDay = {
	/**  `YYYY-MM-DD` */
	date: string,
	count: number,
};

/**
 *  `GET /api/github/contributions/:username`
 * 
 *  以前是前端直接打第三方的 `github-contributions-api.jogruber.de`——那是一個**爬
 *  GitHub 個人頁 HTML** 的服務。GitHub 的 REST API 沒有貢獻資料,但 GraphQL 有官方的
 *  `contributionsCollection.contributionCalendar`,而我們本來就有 token,所以不是把
 *  jogruber 代理起來,是直接不需要它了。
 */
export type GithubContributionsResponse = {
	contributions: GithubContributionDay[],
	total: number,
	error: string | null,
};

export type GithubEvent = {
	id: string,
	type: string,
	repo: GithubEventRepo,
	created_at: string,
	payload: GithubEventPayload,
};

/**
 *  只保留 PushEvent 用得到的欄位。其他事件型別的 payload 會是空 commits + null
 *  ——前端只 render PushEvent,這裡不為沒人看的事件型別各建一份形狀。
 */
export type GithubEventPayload = {
	commits: GithubCommit[],
	before: string | null,
	head: string | null,
	size: number | null,
};

export type GithubEventRepo = {
	/**  `owner/repo` */
	name: string,
};

/**
 *  `GET /api/github/events/:username`
 * 
 *  原本直接回一個 JSON 陣列(GitHub 錯誤時回 GitHub 的錯誤物件),而前端的型別寫成
 *  `GithubEvent[] & { error?: string }` —— 陣列身上不會有 `.error`,那個交集型別是假的。
 *  改成包一層讓 error 成為真的欄位。
 */
export type GithubEventsResponse = {
	events: GithubEvent[],
	error: string | null,
};

/**  `GET /api/github/repos/:username` 的一列。 */
export type GithubRepo = {
	id: number,
	name: string,
	html_url: string,
	description: string | null,
	language: string | null,
	stargazers_count: number,
};

/**
 *  `GET /api/github/repos/:username`
 * 
 *  這支以前不存在——前端直接從瀏覽器打 `api.github.com/users/:u/repos`。那條路是
 *  **未認證**的,額度 60 req/hr 且是算在**讀者的 IP** 上;共用出口(公司 NAT、CGNAT、
 *  VPN)額滿時這一區會靜默空白。收進後端就吃得到 GITHUB_TOKEN 的 5000/hr。
 */
export type GithubReposResponse = {
	repos: GithubRepo[],
	error: string | null,
};

/**  `GET /api/github/user/:username` */
export type GithubUserResponse = {
	login: string | null,
	name: string | null,
	avatar_url: string | null,
	html_url: string | null,
	public_repos: number | null,
	error: string | null,
};

/**  不公開的一筆(給後台列「藏了哪些」,Spotify 的歌不在最近播放裡也看得到) */
export type HiddenItem = {
	kind: string,
	key: string,
	title: string,
	hidden_at: string,
};

/**  `GET /api/admin/keyword-filters`(requireAdmin)。`{ filters: rows }`(SELECT *;目前空表)。 */
export type KeywordFilterRow = {
	id: number,
	keyword: string,
	action: string | null,
	created_at: string,
};

export type KeywordFiltersResponse = {
	filters: KeywordFilterRow[],
};

export type LinkPreviewResponse = {
	/**  目標頁標題(og:title → twitter:title → <title>) */
	title: string | null,
	/**  摘要(og:description → twitter:description → meta description) */
	description: string | null,
	/**  預覽圖(og:image → twitter:image);沒有就是 None → 前端走降級卡 */
	image: string | null,
	/**  站名(og:site_name),沒有則退回 host */
	site_name: string | null,
	/**
	 *  favicon 的絕對網址(降級卡用)。優先取站方 `<link rel="icon">` 宣告的那支,
	 *  沒宣告才退回猜 `/favicon.ico`——後者很多站根本沒有(見 `link_icon_href`)。
	 */
	favicon: string | null,
};

/**  只回一句訊息的成功回應(刪除、確認類)。 */
export type MessageResponse = {
	message: string,
};

export type MetricStat = {
	metric: string,
	count: number,
	p75: number | null,
	good: number,
	needs_improvement: number,
	poor: number,
};

/**  `GET /api/spotify/now-playing`。沒在播 / 未配置 / 抓取失敗一律回 is_playing:false。 */
export type NowPlayingResponse = {
	is_playing: boolean,
	item: SpotifyTrack | null,
	progress_ms: number | null,
};

/**
 *  `GET /api/watch/now` 的 `watching`。原本是 in-memory 的 serde_json::Value,
 *  specta 生不出型別,前端只好手寫一份 LiveNow。
 * 
 *  兩個寫入點(動畫瘋擴充的 heartbeat、Trakt 輪詢)欄位集合本來就一致,
 *  各欄位的正規型別也是確定的,不是猜的:
 *    episode  —— 擴充送的是 `ep ? ep[1] : null`(regex 捕獲組,必為字串);
 *                anime_history.episode 是 TEXT(anigamer SDK 已正規化成 Option<String>);
 *                Trakt 那條是 format!("S{:02}E{:02}")。三個來源都是字串。
 *    tmdbId   —— anime_history.tmdb_id 是 INTEGER;Trakt 的 /ids/tmdb 是數字。
 *    progressPct —— 兩條路徑都先 round 成整數才存。
 * 
 *  ⚠ expiresAt 不在這裡:那是伺服器記帳(TTL),不是 API 資料。
 *  舊寫法把它塞進同一個 JSON、serve 時再 remove("expiresAt"),靠「記得移除」維持正確;
 *  現在改由 WatchState 以 (NowWatching, expires_at_ms) 分開存,型別上就不可能洩漏。
 */
export type NowWatching = {
	/**
	 *  目前只會是 "anime"——唯一的產生者是 bahamut 的 heartbeat。
	 *  舊資料裡還有 "movie" / "tv"(Trakt 時期),型別因此保持字串不收窄。
	 */
	type: string,
	title: string,
	cover: string | null,
	tmdbId: number | null,
	episode: string | null,
	progressPct: number | null,
	/**  目前只會是 "bahamut"(Trakt 輪詢已移除)。歷史列仍可能是 "trakt"。 */
	source: string,
	externalUrl: string | null,
	/**  epoch ms;與 endsAt 一起給前端做 client 端進度插值 */
	startedAt: number,
	/**  bahamut 的 heartbeat 給不出結束時間,所以目前恆為 None(Trakt 那條已移除) */
	endsAt: number | null,
};

/**
 *  單一 OAuth provider 的公開設定。clientId 是公開值(前端組授權 URL 要用),
 *  沒設定時是空字串而不是缺欄位——所以 enabled 才是「這個 provider 能不能用」的判準。
 */
export type OAuthProviderInfo = {
	clientId: string,
	enabled: boolean,
};

export type Pagination = {
	page: number,
	limit: number,
	total: number,
	totalPages: number,
};

/**  exifr `pick` 的那組欄位(key 大小寫照 exifr 原樣,make/model 是小寫的)。 */
export type PhotoExif = {
	make: string | null,
	model: string | null,
	LensModel: string | null,
	FocalLength: ExifValue | null,
	FocalLengthIn35mmFormat: ExifValue | null,
	FNumber: ExifValue | null,
	ExposureTime: ExifValue | null,
	ISO: ExifValue | null,
	/**
	 *  拍攝時間。本檔寫的是帶相機自身時區的 ISO 8601(`"2023-04-27T10:56:22+08:00"`);
	 *  相機沒寫 OffsetTime* 時退成不帶時區的裸本地時間。
	 * 
	 *  ⚠️ 舊 manifest 裡還有兩種歷史格式:Node builder 寫的 exiftool 原樣
	 *  `"2023:04:27 10:56:22"`,以及本檔舊版拿容器 TZ 硬轉的 `"…Z"`。
	 *  前端的 `src/lib/exifDate.ts` 三種都吃;`scripts/backfill-exif-dates.ts` 負責收斂。
	 */
	DateTimeOriginal: string | null,
	Software: string | null,
	Flash: string | null,
	WhiteBalance: string | null,
	MeteringMode: string | null,
};

/**
 *  只有舊 builder 會寫(線上 247 張裡 2 張有)。三個數字都只從 JSON 讀進來,
 *  而 JSON 表達不了 NaN/Inf,所以是 `number` 而不是 f64 預設的 `number | null`。
 */
export type PhotoGps = {
	latitude: number,
	longitude: number,
	altitude: number | null,
};

/**  同一張照片的四個尺寸;sync 產出時 full/regular 同檔、small/thumb 同檔。 */
export type PhotoUrls = {
	full: string,
	regular: string,
	small: string,
	thumb: string,
};

/**  `GET /api/gallery/photos` */
export type PhotosManifest = {
	version: string,
	generatedAt: string,
	totalPhotos: number,
	photos: GalleryPhoto[],
};

export type PollOptionRow = {
	option_key: string,
	count: number,
};

export type PollResponse = {
	options: PollOptionRow[],
	total: number,
};

/**
 *  `GET /api/posts/:id` 成功回應。欄位序對齊舊 `json!` 的 key 序。
 *  404 路徑(找不到 / 該語系無內容)仍是各自的錯誤 JSON,不走這個型別。
 */
export type PostDetailResponse = {
	message: string,
	id: number,
	/**  canonical 網址用的 slug;前端拿它把非 canonical 的網址 301 過去。 */
	slug: string | null,
	title: string,
	content: string,
	excerpt: string,
	/**  摘要裡連到章節的句子(這個語系的;摘要裡找不到的已濾掉)。 */
	excerpt_links: ExcerptLink[],
	category: string | null,
	status: string,
	author: string | null,
	view_count: number,
	likes: number,
	layout_type: string | null,
	allow_comments: boolean,
	/**  內容格式:'markdown'(預設)| 'mdx'。前端據此選渲染管線。 */
	format: string | null,
	series_name: string | null,
	series_order: number | null,
	created_at: string,
	updated_at: string | null,
	locale: string,
	source_language: string,
	is_source: boolean,
	available_locales: string[],
	tags: string[],
};

/**  `GET /api/posts` 的單篇摘要。`title`/`excerpt` 已依 `?lang=` 取好該語系內容。 */
export type PostListItem = {
	id: number,
	slug: string | null,
	title: string,
	excerpt: string,
	/**
	 *  該語系內文的前 260 個 UTF-16 code unit(= JS `content.substring(0,260)`)。
	 *  列表卡片顯示的是內文截斷而非 AI 摘要(見 Blog.tsx NoteCard),但整篇 content
	 *  進列表要多 ~188KB,所以只送前端截斷所需的長度。
	 */
	content_preview: string,
	/**  該語系內文的長度(字元數)。手記列表用它估閱讀時間、決定那篇文章的星軌拖多長。 */
	content_length: number,
	category: string | null,
	status: string,
	author: string | null,
	view_count: number,
	likes: number,
	/**
	 *  `post_reactions` 裡 ❤️ 的數量——列表卡片的愛心顯示這個,不是上面的 `likes`。
	 * 
	 *  兩個數字並存是有歷史的:`posts.likes` 是舊的按讚計數器(`/api/posts/:id/like`),
	 *  而文章頁下方的 emoji 反應列另外存在 `post_reactions`。同一顆愛心在列表卡片走
	 *  前者、在文章頁的反應列走後者,於是同一篇文章會出現兩個不一樣的數字——使用者
	 *  看到的「愛心沒有同步」就是這個。
	 * 
	 *  統一成以 `post_reactions.❤️` 為準。`likes` 欄位留著不動(舊資料還在,而且
	 *  `/api/posts/:id/like` 還有其他呼叫端),但前端不再顯示它。
	 */
	heart_count: number,
	layout_type: string | null,
	allow_comments: boolean,
	created_at: string,
	updated_at: string | null,
	source_language: string,
	available_locales: string[],
	tags: string[],
};

export type PostsListResponse = {
	message: string,
	posts: PostListItem[],
	locale: string | null,
	pagination: Pagination,
};

export type ReactionRow = {
	emoji: string,
	count: number,
};

export type ReactionsResponse = {
	reactions: ReactionRow[],
};

export type RecentPlayItem = {
	track: SpotifyTrack,
	played_at: string,
};

/**  `GET /api/spotify/recently-played` */
export type RecentlyPlayedResponse = {
	items: RecentPlayItem[],
};

export type SeriesDetailResponse = {
	name: string,
	posts: SeriesPostRow[],
};

export type SeriesListResponse = {
	series: SeriesRow[],
};

/**  `GET /api/series/:name` 單列:某系列下的文章(精簡欄位)。 */
export type SeriesPostRow = {
	id: number,
	title: string,
	excerpt: string | null,
	series_name: string | null,
	series_order: number | null,
	created_at: string,
};

/**  `GET /api/series` 單列:系列名 + 篇數 + 起訖時間。 */
export type SeriesRow = {
	name: string,
	count: number,
	first_at: string | null,
	last_at: string | null,
};

export type SpotifyAlbum = {
	name: string,
	images: SpotifyImage[],
	/**  'YYYY' / 'YYYY-MM' / 'YYYY-MM-DD'(Spotify 依 precision 給不同長度)—— 前端只取年份 */
	release_date: string,
};

export type SpotifyArtist = {
	name: string,
};

export type SpotifyExternalUrls = {
	spotify: string,
};

export type SpotifyImage = {
	url: string,
};

export type SpotifyTrack = {
	id: string,
	name: string,
	artists: SpotifyArtist[],
	album: SpotifyAlbum,
	duration_ms: number,
	external_urls: SpotifyExternalUrls,
	/**  0–100,前端拿來算平均熱門度 */
	popularity: number,
	explicit: boolean,
};

export type StatsResponse = {
	message: string,
	total_posts: number,
	total_chars: number,
	days: number,
};

/**  miniprofile 客製(動態頭像 / 頭像框 / 名牌動畫)。抓不到的就是 None。 */
export type SteamCustomization = {
	animatedAvatar: string | null,
	avatarFrame: string | null,
	nameplateWebm: string | null,
	nameplateMp4: string | null,
	featuredBadge: SteamFeaturedBadge | null,
};

/**  miniprofile 頁面刮下來的展示徽章(三個都是 regex 捕獲組,必為字串)。 */
export type SteamFeaturedBadge = {
	icon: string,
	name: string,
	/**  Steam 頁面上是 "1,234 XP" 這種已格式化的字串,不是數字 */
	xp: string,
};

export type SteamGame = {
	appid: number | null,
	name: string | null,
	playtime_2weeks: number | null,
	playtime_forever: number | null,
};

/**
 *  `GET /api/steam/recent-games` 與 `GET /api/steam/owned-games`
 *  (`gameCount` 只有 owned-games 會有;那是我們自己的欄位名,故 camelCase)。
 */
export type SteamGamesResponse = {
	games: SteamGame[],
	gameCount: number | null,
	error: string | null,
};

/**  GetPlayerSummaries 的 `players[0]` 裡我們用得到的欄位(欄位名沿用 Steam 的)。 */
export type SteamPlayer = {
	personaname: string | null,
	avatarfull: string | null,
	profileurl: string | null,
	/**  Steam 的狀態 enum(1 = 上線) */
	personastate: number | null,
	/**  正在玩的 appid。Steam 這欄回**字串**不是數字(有值就代表在遊戲中) */
	gameid: string | null,
};

/**
 *  `GET /api/steam/player`
 * 
 *  原本原樣回 Steam 的 `{response:{players:[…]}}`,前端自己挖 `response.players[0]`。
 *  這裡把那層挖掉——一個 steamid 就只會有一個 player。
 */
export type SteamPlayerResponse = {
	player: SteamPlayer | null,
	error: string | null,
};

/**  `/api/steam/profile` 的資料本體(=快取內容)。 */
export type SteamProfile = {
	player: SteamPlayer,
	level: number,
	xp: number,
	xpToNext: number,
	badgeCount: number,
	customization: SteamCustomization,
	profileUrl: string,
};

/**
 *  `GET /api/steam/profile`
 * 
 *  `_cachedAt` 是伺服器記帳(SWR 的抓取時間),不是 profile 的一部分——所以它在
 *  回應型別上,而快取只存 profile 本體(同 watch/now 把 expiresAt 移出 wire type)。
 */
export type SteamProfileResponse = {
	/**  epoch ms */
	_cachedAt: number,
} & SteamProfile;

/**  `GET /api/newsletter/by-token/:token` 的回應(顯式 3 欄)。 */
export type SubscriberByToken = {
	email: string,
	name: string | null,
	status: string | null,
};

/**  `newsletter_subscribers` 一列(`SELECT *`)。欄位序 = 表宣告序,對齊舊 `row_to_json`。 */
export type SubscriberRow = {
	id: number,
	email: string,
	name: string | null,
	status: string | null,
	subscribed_at: string | null,
	unsubscribed_at: string | null,
	unsubscribe_token: string | null,
};

export type SubscribersResponse = {
	message: string,
	subscribers: SubscriberRow[],
	pagination: Pagination,
};

/**  `POST /api/admin/tags` 的 201 回應。 */
export type TagCreated = {
	id: number,
	name: string,
	post_count: number,
};

/**
 *  公開標籤列表的單列。欄位順序 = SELECT 欄位順序 = Express JSON key 順序,
 *  以確保 byte-level 對拍等價(serde 依宣告順序序列化)。
 *  One row of the public tag list. Field order = SELECT column order = Express JSON key
 *  order, so serialization is byte-equivalent (serde serializes in declaration order).
 */
export type TagRow = {
	id: number,
	name: string,
	/**
	 *  直接保留 sqlite 原始 TEXT(例 `"2026-04-04 19:16:29"`),不經 chrono 解析,
	 *  避免格式漂移(Express 也是原樣丟出 DATETIME 字串)。
	 */
	created_at: string,
	post_count: number,
	/**  顯示用譯名(name 仍是資料鍵)。沒填就由前端 fallback 回 name。 */
	name_en: string | null,
	name_ja: string | null,
	name_ko: string | null,
	name_zh_cn: string | null,
};

/**
 *  `PUT /api/admin/tags/{id}` 的 200 回應。
 * 
 *  `id` 原本是**字串**(來源是 `Path<String>`)而建立時是數字(`last_insert_rowid()`)。
 *  路徑參數換成 `PathParam<i64>` 之後這個不一致自己就沒了。
 *  前端不讀這個欄位(只看 `response.ok` 然後重抓清單),所以改型別沒有影響。
 */
export type TagUpdated = {
	id: number,
	name: string,
	updated: number,
};

export type TagsResponse = {
	message: string,
	tags: TagRow[],
};

/**  `GET /api/telemetry` 的回應。每個欄位讀不到就是 null(例如換了機器、沒有那顆感測器) */
export type Telemetry = {
	/**  CPU 溫度(°C):k10temp 的 Tctl */
	cpuTemp: number | null,
	/**  一分鐘平均負載除以邏輯核心數(百分比,可能超過 100) */
	load: number | null,
	/**  記憶體用了幾成(百分比):(總量 − 可用) / 總量 */
	memory: number | null,
	/**  APU 整顆的功耗(W):amdgpu 的 power1_input(APU 回報的是整顆封裝) */
	power: number | null,
};

export type ThoughtDetailResponse = {
	message: string,
	thought: ThoughtOut,
};

/**  對外輸出的 thought:欄位順序 = Express `{ ...r, edited, ref }` 後的實際 key 順序。 */
export type ThoughtOut = {
	id: number,
	content: string,
	ref_type: string | null,
	ref_url: string | null,
	ref_json: string | null,
	likes: number,
	created_at: string,
	updated_at: string | null,
	edited: boolean,
	dislikes: number,
	comment_count: number,
	/**  watched / read / listened / played / shared;null 是一般的碎念 */
	verb: string | null,
	/**  Express 的 `ref: safeParse(r.ref_json)`:解析成功→物件、失敗或 null→JSON null。 */
	ref: ThoughtRef | null,
};

/**  `POST /api/thoughts/:id/react` 的回應。 */
export type ThoughtReactResponse = {
	message: string,
	likes: number,
	dislikes: number,
};

/**
 *  `ref_json` 解析後的物件。這欄不是自由格式——本 repo 裡只有兩個產生者:
 *    - `unfurl_url`(`ref_type="link"`)→ title / desc / image / site
 *    - `enrich_media_ref`(`ref_type="media"`)→ source / url / title / overview /
 *      rating / genres / year / poster,外加呼叫端 `ref.json` 帶進來的
 *      kind / mediaType / tmdbId(那三個 enrich 只是 spread 過去,自己不產)
 * 
 *  線上 5 則碎念裡 2 則有 ref,兩則都是 link。media 這條路目前沒有任何 client
 *  走得到(MCP 只送 content/refUrl/clearRef),欄位是照 enrich_media_ref 的
 *  實作列的,不是猜的。
 * 
 *  未列到的 key 會在 `ref` 裡被丟掉,但同一個回應的 `ref_json` 是原封不動的
 *  字串,所以資料不會不見。
 */
export type ThoughtRef = {
	title: string | null,
	desc: string | null,
	image: string | null,
	site: string | null,
	kind: string | null,
	url: string | null,
	source: string | null,
	overview: string | null,
	genres: string | null,
	poster: string | null,
	mediaType: string | null,
	rating: ThoughtRefScalar | null,
	year: ThoughtRefScalar | null,
	tmdbId: ThoughtRefScalar | null,
	/**  歌手、作者 */
	creator: string | null,
	/**  進度,例如動畫看到的那一集 `EP 12`。前台原樣顯示,所以只寫不分語系的寫法 */
	progress: string | null,
	/**  附上的是哪一筆紀錄(`anime:<sn>`、`track:<id>`…),後台用來標「已經寫過」 */
	key: string | null,
};

/**
 *  `ref` 裡少數幾個「字串或數字都可能」的欄位。enrich 自己寫的是字串
 *  (`rating` 走 `format!("{:.1}")`、`year` 取日期前 4 碼),但同一個 key 也可能
 *  來自呼叫端 `ref.json` 的原值,那邊沒有任何東西保證它是字串。
 * 
 *  與 gallery 的 `ExifValue` 刻意各自一份:兩邊的 union 是不同原因造成的
 *  (那邊是兩個寫入端格式不同,這邊是 enrich 覆值與呼叫端原值並存),
 *  綁在一起只會讓其中一邊的註解變成謊話。
 */
export type ThoughtRefScalar = number | string;

export type ThoughtsListResponse = {
	message: string,
	thoughts: ThoughtOut[],
};

/**  `GET /api/watch/tmdb-search` */
export type TmdbSearchResponse = {
	message: string,
	results: TmdbSearchResult[],
};

/**
 *  `GET /api/watch/tmdb-search` 的一列。TMDb 的搜尋回應在這裡重新塑形成前端真正要的
 *  五個欄位(同 spotify 的做法),不是原樣轉發——所以型別就是我們自己的,不是 TMDb 的。
 */
export type TmdbSearchResult = {
	tmdbId: number | null,
	/**  回填請求的 kind("movie" | "tv");TMDb 的 search 端點自己不回這欄 */
	kind: string,
	/**  movie 走 `title`、tv 走 `name`,兩個都沒有才 null */
	title: string | null,
	/**  release_date / first_air_date 的前 4 碼 */
	year: number | null,
	poster: string | null,
};

export type TopGenre = {
	genre: string,
	count: number,
};

/**  `GET /api/spotify/top-genres` */
export type TopGenresResponse = {
	genres: TopGenre[],
};

/**  `GET /api/spotify/top-tracks` */
export type TopTracksResponse = {
	items: SpotifyTrack[],
};

export type TvResponse = {
	message: string,
	series: TvRow[],
};

/**  `GET /api/tv/recent` 一列(GROUP BY series_name 聚合)。 */
export type TvRow = {
	series_name: string,
	last_watched: string | null,
	ep_count: number,
	tmdb_id: number | null,
	poster_url: string | null,
	genres: string | null,
	source: string | null,
};

/**  durations 端點算出來的「實際編碼區間」——第一筆的開始到最後一筆的結束。 */
export type WakatimeActualCodingTime = {
	start: string | null,
	end: string | null,
	hasData: boolean,
};

/**  WakaTime 的 `grand_total`(前端只用 text,total_seconds 一起帶著方便日後算)。 */
export type WakatimeGrandTotal = {
	text: string | null,
	total_seconds: number | null,
};

/**  stats 端點的一列(語言 / 專案共用同一個形狀)。 */
export type WakatimeStat = {
	name: string,
	text: string,
	percent: number,
};

/**
 *  `GET /api/wakatime/week`、`GET /api/wakatime/projects`
 * 
 *  原本回 WakaTime 的 `{data:{languages, projects, editors, …}}` 原樣,前端讀 `.data`。
 *  這裡把 data 攤掉、只留前端會 render 的兩組。
 */
export type WakatimeStatsResponse = {
	languages: WakatimeStat[],
	projects: WakatimeStat[],
	error: string | null,
	details: string | null,
};

/**
 *  `GET /api/wakatime/today`
 * 
 *  原本回 WakaTime 的 `{data:[summary], start, end}` 加上 actualCodingTime,
 *  summary 是一整包(categories / editors / machines / …)而前端只讀
 *  `data[0].grand_total.text`。這裡把那個只有一個元素的陣列攤掉。
 */
export type WakatimeTodayResponse = {
	grand_total: WakatimeGrandTotal | null,
	/**  WakaTime 回的查詢區間(非「實際編碼」區間) */
	start: string | null,
	end: string | null,
	actualCodingTime: WakatimeActualCodingTime,
	error: string | null,
	/**  上游的錯誤內容(原本叫 details,是 parse 過的 body;這裡轉字串好進型別) */
	details: string | null,
};

/**
 *  `GET /api/watch/favorites` 的一列:DB 的 watch_favorites + TMDb 即時在地化。
 *  year 兩個來源都是整數(TMDb 那條走 js_parse_int_opt、DB 欄位是 INTEGER),
 *  所以不是前端手寫版本猜的 string | number。
 */
export type WatchFavoriteRow = {
	id: number,
	/**  "film" | "tv" */
	kind: string,
	tmdbId: number | null,
	rating: number | null,
	quote: string | null,
	/**  TMDb 在地化標題;查不到時退成 `#<tmdbId>`,所以一定有值 */
	title: string,
	poster: string | null,
	year: number | null,
	externalUrl: string,
};

/**  `GET /api/watch/favorites` */
export type WatchFavoritesResponse = {
	message: string,
	favorites: WatchFavoriteRow[],
};

/**  `GET /api/watch/now` */
export type WatchNowResponse = {
	watching: NowWatching | null,
};

/**  `GET /api/watch/stats` —— 5 個 count(key 為 camelCase)。 */
export type WatchStatsResponse = {
	message: string,
	animeCount: number,
	animeEpisodes: number,
	filmCount: number,
	tvSeriesCount: number,
	tvEpisodes: number,
};

/**  一件作品的一種語言:GitHub 算的程式碼量(bytes)。 */
export type WorkLanguage = {
	name: string,
	bytes: number,
};

/**  `GET /api/github/works` 的一件作品。 */
export type WorkRepo = {
	/**  `owner/name` */
	repo: string,
	/**  私有 repo 沒有連結(讀者點過去只會看到 404) */
	url: string | null,
	created_at: string,
	pushed_at: string,
	stars: number,
	/**  預設分支上的 commit 數 */
	commits: number,
	/**  由多到少 */
	languages: WorkLanguage[],
};

export type WorksResponse = {
	works: WorkRepo[],
	error: string | null,
};