api.ts
api.ts
// 後端 admin REST API 的薄客戶端:登入拿 JWT、快取、401 自動重登一次。
// 憑證從環境變數來(見 index.ts),token 只存在記憶體、不落地。
/**
* unknown → 可讀的文字。字串原樣、其餘 JSON.stringify。
* 原本寫 `String(v)`:後端的 error 欄位若是物件,錯誤訊息就變成一行 `[object Object]`。
*/
function toText(v: unknown): string {
return typeof v === 'string' ? v : JSON.stringify(v);
}
export interface ApiConfig {
baseUrl: string;
username?: string;
password?: string;
/** 預先簽好的 JWT(可選;設了就跳過 username/password 登入流程)。 */
token?: string;
}
export interface RequestOptions {
query?: Record<string, unknown>;
body?: unknown;
/** 預設 true(帶 Bearer)。公開端點(health/vitals)設 false。 */
auth?: boolean;
}
export class ApiClient {
private token?: string;
constructor(private cfg: ApiConfig) {
this.token = cfg.token;
}
private async login(): Promise<string> {
if (!this.cfg.username || !this.cfg.password) {
throw new Error(
'缺少後台憑證:請設定 KOIMSURAI_ADMIN_USERNAME + KOIMSURAI_ADMIN_PASSWORD(或直接給 KOIMSURAI_ADMIN_TOKEN)',
);
}
const res = await fetch(`${this.cfg.baseUrl}/api/auth/login`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ username: this.cfg.username, password: this.cfg.password }),
});
if (!res.ok) {
throw new Error(`後台登入失敗 (${res.status})——檢查帳密與後端是否在 ${this.cfg.baseUrl}`);
}
const data = (await res.json()) as { token?: string };
if (!data.token) throw new Error('登入回應缺少 token');
this.token = data.token;
return this.token;
}
private async ensureToken(): Promise<string> {
return this.token ?? this.login();
}
async request<T = unknown>(method: string, path: string, opts: RequestOptions = {}): Promise<T> {
const { query, body, auth = true } = opts;
const url = new URL(`${this.cfg.baseUrl}${path}`);
if (query) {
for (const [k, v] of Object.entries(query)) {
if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, toText(v));
}
}
const send = (bearer?: string): Promise<Response> =>
fetch(url, {
method,
headers: {
...(body !== undefined ? { 'content-type': 'application/json' } : {}),
...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
},
body: body !== undefined ? JSON.stringify(body) : undefined,
});
let res: Response;
if (auth) {
res = await send(await this.ensureToken());
// token 過期 / 失效 → 清掉重登一次(僅在有帳密時)
if (res.status === 401 && this.cfg.username && this.cfg.password) {
this.token = undefined;
res = await send(await this.login());
}
} else {
res = await send();
}
const text = await res.text();
let parsed: unknown = null;
if (text) {
try {
parsed = JSON.parse(text);
} catch {
parsed = text;
}
}
if (!res.ok) {
const msg =
parsed && typeof parsed === 'object'
? ((parsed as Record<string, unknown>).error ?? (parsed as Record<string, unknown>).message ?? text)
: text || res.statusText;
throw new Error(`${method} ${path} → ${res.status}: ${toText(msg)}`);
}
return parsed as T;
}
/** 上傳檔案(multipart/form-data,欄位名 file——對齊後端 multer.single('file'))。
* Bearer 認證 + 401 自動清 token 重登一次。FormData 每次 send 重建(body 只能消費一次)。 */
async uploadFile<T = unknown>(path: string, bytes: Uint8Array, filename: string, contentType?: string): Promise<T> {
const send = (bearer: string): Promise<Response> => {
const form = new FormData();
// @types/node 26 起 Uint8Array 泛型化為 Uint8Array<ArrayBufferLike>;Blob/BlobPart 要
// Uint8Array<ArrayBuffer>。bytes 為上傳檔案資料(fs/網路,非 SharedArrayBuffer)→ 收斂型別安全。
const blob = new Blob([bytes as Uint8Array<ArrayBuffer>], contentType ? { type: contentType } : {});
form.append('file', blob, filename);
// 不手動設 content-type:讓 fetch 自動帶 multipart boundary。
return fetch(`${this.cfg.baseUrl}${path}`, {
method: 'POST',
headers: { authorization: `Bearer ${bearer}` },
body: form,
});
};
let res = await send(await this.ensureToken());
if (res.status === 401 && this.cfg.username && this.cfg.password) {
this.token = undefined;
res = await send(await this.login());
}
const text = await res.text();
let parsed: unknown = null;
if (text) {
try {
parsed = JSON.parse(text);
} catch {
parsed = text;
}
}
if (!res.ok) {
const msg =
parsed && typeof parsed === 'object'
? ((parsed as Record<string, unknown>).error ?? (parsed as Record<string, unknown>).message ?? text)
: text || res.statusText;
throw new Error(`POST ${path} → ${res.status}: ${toText(msg)}`);
}
return parsed as T;
}
}