// 由 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,
};