dsh-ds-balance 1.0.0

package/lib/domain/normalize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 归一化与错误体解析。
+ *
+ * 两条铁律：结构不符抛 {@link ShapeError}，金额解析失败抛 {@link ParseError}。
+ * **绝不静默归 0。**
+ * @module dsh-ds-balance/domain/normalize
+ */
+import type { BalanceSnapshot } from './balance.js';
+/**
+ * 生成单调递增、可按字典序排序的快照 id。
+ * @param now - 当前时刻。
+ * @returns 形如 `<时间戳 base36>-<序号 base36>` 的 id。
+ */
+export declare function nextSnapshotId(now: number): string;
+/**
+ * 把上游响应归一化成快照。
+ * @param raw - 上游 JSON，未经信任。
+ * @param accountTag - 账本作用域标识。
+ * @param now - 抓取时刻。
+ * @returns 不可变快照。
+ * @throws {ShapeError} 结构不符。
+ * @throws {ParseError} 金额不是十进制定点。
+ */
+export declare function normalize(raw: unknown, accountTag: string, now: number): BalanceSnapshot;
+/** 从错误体里抽出的可读信息。 */
+export interface ParsedErrorBody {
+    code?: string;
+    message?: string;
+}
+/**
+ * 容错解析上游错误体。
+ *
+ * 官方未文档化，实测至少三种形状，逐条尝试后兜底成截断的原文。
+ * @param text - 响应正文。
+ * @returns 尽力抽出的 code 与 message。
+ */
+export declare function parseErrorBody(text: string): ParsedErrorBody;
+//# sourceMappingURL=normalize.d.ts.map

package/lib/domain/normalize.js

@@ -0,0 +1,120 @@
+/**
+ * 归一化与错误体解析。
+ *
+ * 两条铁律：结构不符抛 {@link ShapeError}，金额解析失败抛 {@link ParseError}。
+ * **绝不静默归 0。**
+ * @module dsh-ds-balance/domain/normalize
+ */
+import { ParseError, ShapeError } from './errors.js';
+import { parseMoney } from './money.js';
+let lastStamp = 0;
+let counter = 0;
+/**
+ * 生成单调递增、可按字典序排序的快照 id。
+ * @param now - 当前时刻。
+ * @returns 形如 `<时间戳 base36>-<序号 base36>` 的 id。
+ */
+export function nextSnapshotId(now) {
+    if (now === lastStamp)
+        counter += 1;
+    else {
+        lastStamp = now;
+        counter = 0;
+    }
+    return `${now.toString(36).padStart(9, '0')}-${counter.toString(36).padStart(3, '0')}`;
+}
+/** 校验一个币种条目。 */
+function toBalanceInfo(entry, index) {
+    if (entry === null || typeof entry !== 'object') {
+        throw new ShapeError(`balance_infos[${index}] is not an object`);
+    }
+    const row = entry;
+    if (typeof row.currency !== 'string' || row.currency.trim() === '') {
+        throw new ShapeError(`balance_infos[${index}].currency is not a non-empty string`);
+    }
+    return {
+        currency: row.currency,
+        total: parseAmount(row.total_balance, `balance_infos[${index}].total_balance`),
+        granted: parseAmount(row.granted_balance, `balance_infos[${index}].granted_balance`),
+        toppedUp: parseAmount(row.topped_up_balance, `balance_infos[${index}].topped_up_balance`),
+    };
+}
+/** 解析一个金额字段，带字段名以便定位。 */
+function parseAmount(value, field) {
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new ShapeError(`${field} is not a string`);
+    }
+    try {
+        return parseMoney(value);
+    }
+    catch (error) {
+        if (error instanceof ParseError)
+            throw new ParseError(`${field}: ${error.message}`, { cause: error });
+        throw error;
+    }
+}
+/**
+ * 把上游响应归一化成快照。
+ * @param raw - 上游 JSON，未经信任。
+ * @param accountTag - 账本作用域标识。
+ * @param now - 抓取时刻。
+ * @returns 不可变快照。
+ * @throws {ShapeError} 结构不符。
+ * @throws {ParseError} 金额不是十进制定点。
+ */
+export function normalize(raw, accountTag, now) {
+    if (raw === null || typeof raw !== 'object')
+        throw new ShapeError('response is not an object');
+    const body = raw;
+    if (typeof body.is_available !== 'boolean')
+        throw new ShapeError('is_available is not a boolean');
+    if (!Array.isArray(body.balance_infos))
+        throw new ShapeError('balance_infos is not an array');
+    return {
+        snapshotId: nextSnapshotId(now),
+        accountTag,
+        fetchedAt: now,
+        isAvailable: body.is_available,
+        balances: body.balance_infos.map((entry, index) => toBalanceInfo(entry, index)),
+        source: 'deepseek-http',
+        raw,
+    };
+}
+/**
+ * 容错解析上游错误体。
+ *
+ * 官方未文档化，实测至少三种形状，逐条尝试后兜底成截断的原文。
+ * @param text - 响应正文。
+ * @returns 尽力抽出的 code 与 message。
+ */
+export function parseErrorBody(text) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return {};
+    let body;
+    try {
+        body = JSON.parse(trimmed);
+    }
+    catch {
+        return { message: trimmed.slice(0, 200) };
+    }
+    if (body === null || typeof body !== 'object')
+        return { message: String(body).slice(0, 200) };
+    const record = body;
+    const nested = record.error;
+    if (nested !== null && typeof nested === 'object') {
+        const inner = nested;
+        const code = inner.type ?? inner.code;
+        const message = inner.message;
+        return {
+            ...(typeof code === 'string' && code !== '' ? { code } : {}),
+            ...(typeof message === 'string' ? { message } : {}),
+        };
+    }
+    if (typeof record.detail === 'string')
+        return { message: record.detail };
+    if (typeof record.message === 'string')
+        return { message: record.message };
+    return { message: JSON.stringify(body).slice(0, 200) };
+}
+//# sourceMappingURL=normalize.js.map

package/lib/domain/select.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 多币种选择。
+ *
+ * **后端权威**：前端不再自己挑币种，只读 `selected`。数组顺序可能跳变，
+ * 所以这里先做一次稳定排序再走优先级链。
+ * @module dsh-ds-balance/domain/select
+ */
+import type { BalanceInfo } from './balance.js';
+/** `displayCurrency` 的「跟随账户」取值。 */
+export declare const AUTO_CURRENCY = "auto";
+/**
+ * 稳定排序：`CNY` 排到最前，其余保持原有相对顺序。
+ * @param balances - 上游给的数组，顺序不可依赖。
+ * @returns 新数组，不改动入参。
+ */
+export declare function stableOrder(balances: readonly BalanceInfo[]): BalanceInfo[];
+/**
+ * 按偏好挑选要展示的币种。
+ *
+ * 优先级：偏好币种（且余额 > 0）→ `CNY` 且 > 0 → 任一 > 0 → `CNY` → 第一个 → `null`。
+ * @param balances - 上游给的数组。
+ * @param preferred - 前端传来的 `displayCurrency`；`auto` 或空表示不指定。
+ * @returns 选中的余额项，或 `null` 表示账户没有任何币种。
+ */
+export declare function pickBalance(balances: readonly BalanceInfo[], preferred?: string): BalanceInfo | null;
+//# sourceMappingURL=select.d.ts.map

package/lib/domain/select.js

@@ -0,0 +1,51 @@
+/**
+ * 多币种选择。
+ *
+ * **后端权威**：前端不再自己挑币种，只读 `selected`。数组顺序可能跳变，
+ * 所以这里先做一次稳定排序再走优先级链。
+ * @module dsh-ds-balance/domain/select
+ */
+import { isZeroMoney } from './money.js';
+/** `displayCurrency` 的「跟随账户」取值。 */
+export const AUTO_CURRENCY = 'auto';
+/**
+ * 稳定排序：`CNY` 排到最前，其余保持原有相对顺序。
+ * @param balances - 上游给的数组，顺序不可依赖。
+ * @returns 新数组，不改动入参。
+ */
+export function stableOrder(balances) {
+    return [...balances].sort((left, right) => {
+        if (left.currency === right.currency)
+            return 0;
+        if (left.currency === 'CNY')
+            return -1;
+        if (right.currency === 'CNY')
+            return 1;
+        return 0;
+    });
+}
+/**
+ * 按偏好挑选要展示的币种。
+ *
+ * 优先级：偏好币种（且余额 > 0）→ `CNY` 且 > 0 → 任一 > 0 → `CNY` → 第一个 → `null`。
+ * @param balances - 上游给的数组。
+ * @param preferred - 前端传来的 `displayCurrency`；`auto` 或空表示不指定。
+ * @returns 选中的余额项，或 `null` 表示账户没有任何币种。
+ */
+export function pickBalance(balances, preferred) {
+    if (balances.length === 0)
+        return null;
+    const ordered = stableOrder(balances);
+    const wanted = preferred?.trim() ?? '';
+    if (wanted !== '' && wanted !== AUTO_CURRENCY) {
+        const hit = ordered.find((item) => item.currency.toUpperCase() === wanted.toUpperCase() && !isZeroMoney(item.total));
+        if (hit !== undefined)
+            return hit;
+    }
+    return ordered.find((item) => item.currency === 'CNY' && !isZeroMoney(item.total))
+        ?? ordered.find((item) => !isZeroMoney(item.total))
+        ?? ordered.find((item) => item.currency === 'CNY')
+        ?? ordered[0]
+        ?? null;
+}
+//# sourceMappingURL=select.js.map

package/lib/domain/severity.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 严重度判定。
+ *
+ * **阈值只在这里被读**：前端不参与任何金额比较，颜色完全来自本模块的输出。
+ * @module dsh-ds-balance/domain/severity
+ */
+import type { BalanceInfo, Currency, Severity, ThresholdPair } from './balance.js';
+/** 判定阈值所需的配置切片。 */
+export interface ThresholdConfig {
+    cnyWarn: number;
+    cnyCritical: number;
+    usdWarn: number;
+    usdCritical: number;
+}
+/** 阈值按币种取；没有专属配置的币种一律 `{ warn: 0, critical: 0 }`。 */
+export declare function thresholdsOf(config: ThresholdConfig): Record<Currency, ThresholdPair>;
+/**
+ * 取某个币种的阈值。
+ * @param currency - 币种代码。
+ * @param thresholds - {@link thresholdsOf} 的产物。
+ * @returns 该币种的阈值；没有配置时返回全零，使该币种永远判为 `ok`。
+ */
+export declare function thresholdsFor(currency: Currency, thresholds: Record<Currency, ThresholdPair>): ThresholdPair;
+/**
+ * 判定严重度。
+ *
+ * 顺序即优先级：**不可用压过阈值**；没有任何选定币种时为 `unknown`。
+ * @param selected - 选定的币种余额；为 `null` 时返回 `unknown`。
+ * @param isAvailable - 上游 `is_available`。
+ * @param thresholds - 该币种的阈值。
+ * @returns 闭集内的严重度。
+ */
+export declare function severityOf(selected: BalanceInfo | null, isAvailable: boolean, thresholds: ThresholdPair): Severity;
+//# sourceMappingURL=severity.d.ts.map

package/lib/domain/severity.js

@@ -0,0 +1,44 @@
+/**
+ * 严重度判定。
+ *
+ * **阈值只在这里被读**：前端不参与任何金额比较，颜色完全来自本模块的输出。
+ * @module dsh-ds-balance/domain/severity
+ */
+import { cmpMoney, parseMoney } from './money.js';
+/** 阈值按币种取；没有专属配置的币种一律 `{ warn: 0, critical: 0 }`。 */
+export function thresholdsOf(config) {
+    return {
+        CNY: { warn: parseMoney(config.cnyWarn), critical: parseMoney(config.cnyCritical) },
+        USD: { warn: parseMoney(config.usdWarn), critical: parseMoney(config.usdCritical) },
+    };
+}
+/**
+ * 取某个币种的阈值。
+ * @param currency - 币种代码。
+ * @param thresholds - {@link thresholdsOf} 的产物。
+ * @returns 该币种的阈值；没有配置时返回全零，使该币种永远判为 `ok`。
+ */
+export function thresholdsFor(currency, thresholds) {
+    return thresholds[currency] ?? { warn: 0n, critical: 0n };
+}
+/**
+ * 判定严重度。
+ *
+ * 顺序即优先级：**不可用压过阈值**；没有任何选定币种时为 `unknown`。
+ * @param selected - 选定的币种余额；为 `null` 时返回 `unknown`。
+ * @param isAvailable - 上游 `is_available`。
+ * @param thresholds - 该币种的阈值。
+ * @returns 闭集内的严重度。
+ */
+export function severityOf(selected, isAvailable, thresholds) {
+    if (selected === null)
+        return 'unknown';
+    if (!isAvailable)
+        return 'unavailable';
+    if (cmpMoney(selected.total, thresholds.critical) <= 0)
+        return 'critical';
+    if (cmpMoney(selected.total, thresholds.warn) <= 0)
+        return 'warn';
+    return 'ok';
+}
+//# sourceMappingURL=severity.js.map

package/lib/http/handlers.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 六个端点的处理实现。
+ *
+ * 依赖全部构造注入、**不碰 `ctx`** —— 因此它能脱离宿主直接测。
+ *
+ * 铁律（见 docs/backend-architecture.md §19 第 3、4 条）：
+ * - **任何 handler 都不许把异常抛出去**。抛出去会被宿主包成 500，前端就拿不到
+ *   `error` 结构了。余额端点的业务错误一律走 `200 + state: error`。
+ * - **每次请求现读配置**，不许在闭包里捕获旧值。
+ * @module dsh-ds-balance/http/handlers
+ */
+import type { CoreStore } from '../ports/core-store.js';
+import type { DeepSeekClient } from '../ports/deepseek-client.js';
+import type { Credentials } from '../ports/credentials.js';
+import type { Logger } from '../ports/logger.js';
+import type { ReadableMetrics } from '../ports/metrics.js';
+import type { BalanceService } from '../services/balance-service.js';
+import type { ConfigService } from '../services/config-service.js';
+import type { KeyResolver } from '../services/key-resolver.js';
+import type { Scheduler } from '../services/scheduler.js';
+/** 一套 handler 需要的全部依赖。 */
+export interface HttpDeps {
+    service: BalanceService;
+    config: ConfigService;
+    keys: KeyResolver;
+    client: DeepSeekClient;
+    store: CoreStore;
+    scheduler: Scheduler;
+    logger?: Logger | undefined;
+    /** 可读出聚合值的指标；没接线时返回 `null` 而不是编一份空的。 */
+    metrics?: ReadableMetrics | undefined;
+    /** 凭据端口。只用来读「配没配 / 可不可写」，**永远不读值**。 */
+    credentials?: Credentials | undefined;
+}
+/** `GET /api/v1/balance`。**状态码始终 200**，业务错误走 `state` + `error`。 */
+export declare function handleBalance(request: Request, deps: HttpDeps): Promise<Response>;
+/** `POST /api/v1/balance/refresh`。请求体 `{ reason }`，可省略。 */
+export declare function handleRefresh(request: Request, deps: HttpDeps): Promise<Response>;
+/** `GET /api/v1/config`。**掩码是手动的** —— 本响应自己构造，不走 settings 读取。 */
+export declare function handleConfigGet(_request: Request, deps: HttpDeps): Promise<Response>;
+/** `POST /api/v1/config`。请求是任意字段子集；形状不合法或校验失败一律 `422`。 */
+export declare function handleConfigUpdate(request: Request, deps: HttpDeps): Promise<Response>;
+/** `POST /api/v1/test-connection`。**不动活动缓存。** */
+export declare function handleTestConnection(request: Request, deps: HttpDeps): Promise<Response>;
+/** `GET /api/v1/healthz`。 */
+export declare function handleHealthz(_request: Request, deps: HttpDeps): Promise<Response>;
+//# sourceMappingURL=handlers.d.ts.map

package/lib/http/handlers.js

@@ -0,0 +1,261 @@
+/**
+ * 六个端点的处理实现。
+ *
+ * 依赖全部构造注入、**不碰 `ctx`** —— 因此它能脱离宿主直接测。
+ *
+ * 铁律（见 docs/backend-architecture.md §19 第 3、4 条）：
+ * - **任何 handler 都不许把异常抛出去**。抛出去会被宿主包成 500，前端就拿不到
+ *   `error` 结构了。余额端点的业务错误一律走 `200 + state: error`。
+ * - **每次请求现读配置**，不许在闭包里捕获旧值。
+ * @module dsh-ds-balance/http/handlers
+ */
+import { classify } from '../domain/errors.js';
+import { CONFIG_FIELDS } from '../config.js';
+import { PLUGIN_VERSION, SCHEMA_VERSION } from '../version.js';
+import { newRequestId, toWireBalanceView, toWireError, } from './wire.js';
+/** `testConnection` 超时的可接受区间；越界一律回落默认值。 */
+const TEST_TIMEOUT_RANGE = { min: 1000, max: 60_000 };
+/** 未配置 API Key 时回给「测试连接」的错误文案。 */
+const NO_KEY_MESSAGE = 'no API key configured';
+/** 统一的 JSON 响应头。 */
+const JSON_HEADERS = { 'content-type': 'application/json; charset=utf-8' };
+/** 造一个 JSON 响应。 */
+function json(body, status = 200) {
+    return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+/** 是否是普通对象（数组与 `null` 都不算）。 */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 把未知异常压成一行。**绝不带凭据** —— 异常里不含密钥是上游的约定。 */
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** 读一个查询参数；URL 坏掉时返回 `null`。 */
+function queryParam(request, name) {
+    try {
+        return new URL(request.url).searchParams.get(name);
+    }
+    catch {
+        return null;
+    }
+}
+/** 读一个 JSON 对象请求体；不是对象、不是 JSON、没有体一律 `null`。 */
+async function readJsonObject(request) {
+    try {
+        const body = await request.json();
+        return isPlainObject(body) ? body : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 空视图：任何 handler 在彻底失败时都回它，保证响应形状仍然合法。
+ * @param requestId - 本次请求的标识。
+ * @param error - 触发失败的异常。
+ * @param state - 要报告的状态；余额端点固定 `error`。
+ * @returns 契约 §8.3 的响应体。
+ */
+function failureView(requestId, error, state = 'error') {
+    return {
+        requestId,
+        schemaVersion: SCHEMA_VERSION,
+        state,
+        stale: false,
+        fetchedAt: 0,
+        ageMs: 0,
+        isAvailable: false,
+        accountTag8: '',
+        balances: [],
+        selected: null,
+        severity: 'unknown',
+        thresholds: {},
+        todayUsage: null,
+        error: toWireError(classify(error)),
+    };
+}
+/** 从配置里挑出 `GET /api/v1/config` 要回传的字段。**`apiKey` 永不出现在这里。** */
+function publicConfig(config) {
+    const { apiKey: _secret, ...rest } = config;
+    return rest;
+}
+/**
+ * `apiKey` 的掩码。
+ *
+ * **不回传密钥的任何片段**：只回答「配没配」。回一个固定长度的星号串是为了让
+ * 字段名 `apiKeyMasked` 名副其实，同时不给任何爆破线索。
+ * @param value - 当前生效的 `apiKey`。
+ * @returns 已配置时是固定长度的掩码串，未配置时是空串。
+ */
+function maskApiKey(value) {
+    return value.trim() === '' ? '' : '********';
+}
+/** `GET /api/v1/balance`。**状态码始终 200**，业务错误走 `state` + `error`。 */
+export async function handleBalance(request, deps) {
+    const requestId = newRequestId();
+    try {
+        const currency = queryParam(request, 'currency');
+        const view = await deps.service.getView(currency === null || currency === '' ? {} : { currency });
+        return json(toWireBalanceView(view, deps.service.accountTag8() ?? '', requestId));
+    }
+    catch (error) {
+        deps.logger?.error('ds-balance: balance handler failed', { requestId, error: describe(error) });
+        return json(failureView(requestId, error));
+    }
+}
+/** `POST /api/v1/balance/refresh`。请求体 `{ reason }`，可省略。 */
+export async function handleRefresh(request, deps) {
+    const requestId = newRequestId();
+    try {
+        const body = await readJsonObject(request);
+        const rawReason = body?.reason;
+        const reason = typeof rawReason === 'string' && rawReason !== '' ? rawReason : 'manual';
+        const result = await deps.service.forceRefresh(reason);
+        return json({ requestId, schemaVersion: SCHEMA_VERSION, ...result, error: null });
+    }
+    catch (error) {
+        deps.logger?.error('ds-balance: refresh handler failed', { requestId, error: describe(error) });
+        return json({
+            requestId,
+            schemaVersion: SCHEMA_VERSION,
+            triggered: false,
+            joined: false,
+            cooldownMs: 0,
+            state: 'error',
+            error: toWireError(classify(error)),
+        });
+    }
+}
+/**
+ * 读凭据的只读描述。
+ *
+ * 失败一律回 `null`：界面据此退化成「不知道，就先当只读」，而不是把整张卡片打挂。
+ * @param deps - 注入的依赖。
+ * @param ref - 当前生效的凭据引用名。
+ * @returns 三个事实，或 `null`。
+ */
+async function credentialInfo(deps, ref) {
+    const credentials = deps.credentials;
+    if (credentials === undefined)
+        return null;
+    try {
+        const described = await credentials.describe(ref);
+        return {
+            ref,
+            configured: described.configured === true,
+            source: described.source ?? null,
+            writable: described.writable === true,
+        };
+    }
+    catch (error) {
+        deps.logger?.debug('ds-balance: credential describe failed', { ref, error: describe(error) });
+        return null;
+    }
+}
+/** 组装配置响应体。**`apiKey` 永不出现；掩码是手动的。** */
+async function configBody(requestId, deps) {
+    const config = deps.config.current();
+    return {
+        requestId,
+        schemaVersion: SCHEMA_VERSION,
+        config: publicConfig(config),
+        apiKeyMasked: maskApiKey(config.apiKey),
+        credential: await credentialInfo(deps, config.apiKeyRef),
+        timeoutMs: deps.config.timeoutMs(),
+        error: null,
+    };
+}
+/** `GET /api/v1/config`。**掩码是手动的** —— 本响应自己构造，不走 settings 读取。 */
+export async function handleConfigGet(_request, deps) {
+    const requestId = newRequestId();
+    try {
+        return json(await configBody(requestId, deps));
+    }
+    catch (error) {
+        deps.logger?.error('ds-balance: config read handler failed', { requestId, error: describe(error) });
+        return json({ requestId, schemaVersion: SCHEMA_VERSION, error: toWireError(classify(error)) });
+    }
+}
+/** `POST /api/v1/config`。请求是任意字段子集；形状不合法或校验失败一律 `422`。 */
+export async function handleConfigUpdate(request, deps) {
+    const requestId = newRequestId();
+    let patch;
+    try {
+        const body = await readJsonObject(request);
+        if (body === null)
+            return json({ requestId, error: { code: 'VALIDATION', message: 'body must be a JSON object', retryable: false } }, 422);
+        const unknown = Object.keys(body).filter((key) => !CONFIG_FIELDS.includes(key));
+        if (unknown.length > 0) {
+            return json({ requestId, error: { code: 'VALIDATION', message: `unknown config field: ${unknown.join(', ')}`, retryable: false } }, 422);
+        }
+        patch = body;
+        if (Object.keys(patch).length > 0)
+            await deps.config.update(patch);
+    }
+    catch (error) {
+        deps.logger?.warn('ds-balance: config write rejected', { requestId, error: describe(error) });
+        return json({ requestId, error: toWireError(classify(error)) }, 422);
+    }
+    // 写完立刻回读，让调用方看到落盘后的真实值（掩码同上）。
+    try {
+        return json(await configBody(requestId, deps));
+    }
+    catch (error) {
+        deps.logger?.error('ds-balance: config readback failed', { requestId, error: describe(error) });
+        return json({ requestId, schemaVersion: SCHEMA_VERSION, error: toWireError(classify(error)) });
+    }
+}
+/** `POST /api/v1/test-connection`。**不动活动缓存。** */
+export async function handleTestConnection(request, deps) {
+    const requestId = newRequestId();
+    try {
+        const body = await readJsonObject(request);
+        const config = deps.config.current();
+        const rawBaseUrl = body?.baseUrl;
+        const baseUrl = typeof rawBaseUrl === 'string' && rawBaseUrl.trim() !== '' ? rawBaseUrl.trim() : config.baseUrl;
+        const rawTimeout = Number(body?.timeoutMs);
+        const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout >= TEST_TIMEOUT_RANGE.min && rawTimeout <= TEST_TIMEOUT_RANGE.max
+            ? Math.trunc(rawTimeout)
+            : deps.config.timeoutMs();
+        const rawApiKey = body?.apiKey;
+        const apiKey = typeof rawApiKey === 'string' && rawApiKey.trim() !== ''
+            ? rawApiKey.trim()
+            : await deps.keys.resolve().catch(() => null);
+        if (apiKey === null)
+            return json({ requestId, ok: false, latencyMs: 0, code: 'NO_KEY', message: NO_KEY_MESSAGE });
+        const result = await deps.client.testConnection({ baseUrl, apiKey, timeoutMs });
+        return json({ requestId, schemaVersion: SCHEMA_VERSION, ...result });
+    }
+    catch (error) {
+        deps.logger?.warn('ds-balance: test-connection handler failed', { requestId, error: describe(error) });
+        const info = classify(error);
+        return json({ requestId, schemaVersion: SCHEMA_VERSION, ok: false, latencyMs: 0, code: info.code, message: info.message });
+    }
+}
+/** `GET /api/v1/healthz`。 */
+export async function handleHealthz(_request, deps) {
+    const requestId = newRequestId();
+    const status = deps.service.status();
+    let store = { ok: false, detail: 'health check failed' };
+    try {
+        const health = await deps.store.health();
+        store = { ok: health.ok, detail: health.detail ?? null };
+    }
+    catch (error) {
+        store = { ok: false, detail: describe(error) };
+    }
+    return json({
+        requestId,
+        schemaVersion: SCHEMA_VERSION,
+        version: PLUGIN_VERSION,
+        state: status.state,
+        lastSuccessAt: status.lastSuccessAt,
+        consecutiveFailures: status.consecutiveFailures,
+        scheduler: { running: deps.scheduler.isRunning(), nextRunAt: deps.scheduler.nextRunAt() },
+        store,
+        // 默认组合没有指标 sink，所以把聚合值挂在这里暴露；没接线时是 null。
+        metrics: deps.metrics?.snapshot() ?? null,
+    });
+}
+//# sourceMappingURL=handlers.js.map