dsh-ds-balance 1.0.0

package/lib/ports/logger.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 日志端口。字段化的结构化日志，便于机器筛。
+ * @module dsh-ds-balance/ports/logger
+ */
+/** 结构化日志。 */
+export interface Logger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/lib/ports/logger.js

@@ -0,0 +1,6 @@
+/**
+ * 日志端口。字段化的结构化日志，便于机器筛。
+ * @module dsh-ds-balance/ports/logger
+ */
+export {};
+//# sourceMappingURL=logger.js.map

package/lib/ports/metrics.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 指标端口。
+ * @module dsh-ds-balance/ports/metrics
+ */
+/** 计数、仪表与直方图。 */
+export interface Metrics {
+    counter(name: string, labels?: Record<string, string>): void;
+    gauge(name: string, labels: Record<string, string>, value: number): void;
+    histogram(name: string, labels: Record<string, string>, value: number): void;
+}
+/** 一个直方图的聚合值。 */
+export interface HistogramSummary {
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    /** 最近一次的观测值。 */
+    last: number;
+}
+/**
+ * 指标快照。
+ *
+ * 键是 `名字{标签=值,...}` 的形式，标签按键名排序 —— 同一组标签永远得到同一个键。
+ */
+export interface MetricsSnapshot {
+    counters: Record<string, number>;
+    gauges: Record<string, number>;
+    histograms: Record<string, HistogramSummary>;
+}
+/** 能读出聚合值的指标实现。没有外部 sink 的装配靠它把数字暴露出去。 */
+export interface ReadableMetrics extends Metrics {
+    snapshot(): MetricsSnapshot;
+}
+/** 什么都不做的实现，用于测试与未接线的装配。 */
+export declare const noopMetrics: Metrics;
+//# sourceMappingURL=metrics.d.ts.map

package/lib/ports/metrics.js

@@ -0,0 +1,11 @@
+/**
+ * 指标端口。
+ * @module dsh-ds-balance/ports/metrics
+ */
+/** 什么都不做的实现，用于测试与未接线的装配。 */
+export const noopMetrics = {
+    counter: () => { },
+    gauge: () => { },
+    histogram: () => { },
+};
+//# sourceMappingURL=metrics.js.map

package/lib/services/account-tag.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 账本作用域标识。
+ *
+ * `accountTag` 只用于把快照按凭据分组，**不含明文**，也不可逆推出密钥。
+ * @module dsh-ds-balance/services/account-tag
+ */
+/** 取前多少位十六进制。够区分账本，又不至于过长。 */
+export declare const ACCOUNT_TAG_LENGTH = 32;
+/** 日志里只记前 8 位。 */
+export declare const ACCOUNT_TAG_LOG_LENGTH = 8;
+/**
+ * 计算账本标识。
+ * @param salt - 进程内稳定的服务端盐。
+ * @param apiKey - 明文密钥；**只在内存里流转**。
+ * @returns 32 位十六进制标识。
+ */
+export declare function computeAccountTag(salt: string, apiKey: string): string;
+/**
+ * 日志用的短标识。
+ * @param accountTag - {@link computeAccountTag} 的产物。
+ * @returns 前 8 位。
+ */
+export declare function accountTag8(accountTag: string): string;
+//# sourceMappingURL=account-tag.d.ts.map

package/lib/services/account-tag.js

@@ -0,0 +1,29 @@
+/**
+ * 账本作用域标识。
+ *
+ * `accountTag` 只用于把快照按凭据分组，**不含明文**，也不可逆推出密钥。
+ * @module dsh-ds-balance/services/account-tag
+ */
+import { createHmac } from 'node:crypto';
+/** 取前多少位十六进制。够区分账本，又不至于过长。 */
+export const ACCOUNT_TAG_LENGTH = 32;
+/** 日志里只记前 8 位。 */
+export const ACCOUNT_TAG_LOG_LENGTH = 8;
+/**
+ * 计算账本标识。
+ * @param salt - 进程内稳定的服务端盐。
+ * @param apiKey - 明文密钥；**只在内存里流转**。
+ * @returns 32 位十六进制标识。
+ */
+export function computeAccountTag(salt, apiKey) {
+    return createHmac('sha256', salt).update(apiKey).digest('hex').slice(0, ACCOUNT_TAG_LENGTH);
+}
+/**
+ * 日志用的短标识。
+ * @param accountTag - {@link computeAccountTag} 的产物。
+ * @returns 前 8 位。
+ */
+export function accountTag8(accountTag) {
+    return accountTag.slice(0, ACCOUNT_TAG_LOG_LENGTH);
+}
+//# sourceMappingURL=account-tag.js.map

package/lib/services/balance-service.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 余额缓存与状态机。
+ *
+ * 职责：把「拿密钥 → 调上游 → 归一化 → 落快照」包成一次可合并的请求，并维护缓存状态。
+ * **对外永不抛错**：一切失败都变成 `view.state` 与 `view.error`。
+ * @module dsh-ds-balance/services/balance-service
+ */
+import type { BalanceView, CacheState } from '../domain/balance.js';
+import { type ErrorCode } from '../domain/errors.js';
+import type { Clock } from '../ports/clock.js';
+import type { CoreStore } from '../ports/core-store.js';
+import type { DeepSeekClient } from '../ports/deepseek-client.js';
+import type { Logger } from '../ports/logger.js';
+import { type Metrics } from '../ports/metrics.js';
+import type { ConfigService } from './config-service.js';
+import type { KeyResolver } from './key-resolver.js';
+/** `forceRefresh` 的返回值，形状对齐契约 §8.4。 */
+export interface RefreshResult {
+    triggered: boolean;
+    joined: boolean;
+    cooldownMs: number;
+    state: CacheState;
+}
+/** 调度器需要的状态切片。 */
+export interface BalanceStatus {
+    state: CacheState;
+    errorCode: ErrorCode | null;
+    consecutiveFailures: number;
+    hasSnapshot: boolean;
+    serverRefreshSeconds: number;
+    /** 上游给的 `Retry-After`，优先于自算退避。 */
+    retryAfterMs: number | null;
+    /** 最近一次成功抓取的时刻；从未成功过是 `null`。健康检查要用。 */
+    lastSuccessAt: number | null;
+}
+/** `getView` 的可选参数。 */
+export interface GetViewOptions {
+    /** 跳过新鲜度判据强制拉一次。 */
+    force?: boolean;
+    /** 覆盖展示币种偏好；缺省读配置。 */
+    currency?: string;
+}
+/** 构造参数。 */
+export interface BalanceServiceOptions {
+    client: DeepSeekClient;
+    store: CoreStore;
+    keys: KeyResolver;
+    config: ConfigService;
+    clock: Clock;
+    /** 服务端盐，用来算 `accountTag`。 */
+    salt: string;
+    logger?: Logger | undefined;
+    metrics?: Metrics | undefined;
+}
+/** 余额缓存与状态机。 */
+export declare class BalanceService {
+    private readonly options;
+    private readonly metrics;
+    private snapshot;
+    private state;
+    private error;
+    private failures;
+    private retryAfterMs;
+    private inflight;
+    /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
+    private persistWarned;
+    constructor(options: BalanceServiceOptions);
+    /** 当前状态切片，供调度与健康检查使用。 */
+    status(): BalanceStatus;
+    /**
+     * 当前账本标识的前 8 位；还没有快照时是 `null`。
+     *
+     * **只回前 8 位**：完整 tag 是账本作用域标识，没有对外的理由。
+     */
+    accountTag8(): string | null;
+    /**
+     * 从存储恢复最近快照（挂载时调一次）。
+     *
+     * **按 `accountTag` 过滤**：凭据轮换后 tag 变了，旧快照视为不存在，不混用。
+     * 没有密钥可算 tag 时静默跳过。
+     */
+    restore(): Promise<void>;
+    /**
+     * 取当前视图。
+     *
+     * 有在飞的请求就合并；不 force 且未过期就返回缓存；否则拉一次。
+     */
+    getView(options?: GetViewOptions): Promise<BalanceView>;
+    /**
+     * 手动刷新。
+     *
+     * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     */
+    forceRefresh(reason: string): Promise<RefreshResult>;
+    /** 快照是否还在 `serverRefreshSeconds` 窗口内。**只看时间，不看状态。** */
+    private withinWindow;
+    /**
+     * 能否直接拿缓存顶上。
+     *
+     * 与 {@link withinWindow} 分开：`restore` 要在状态还是 `empty` 时用纯时间判据，
+     * 而这里必须要求 `ok` —— 否则一次失败之后，窗口内的旧快照会让 `getView`
+     * 永远不再重试。
+     */
+    private canServeCache;
+    /** 跑一次真实抓取。**所有异常都在这里被吸收。** */
+    private fetchOnce;
+    /**
+     * 把快照落盘。
+     *
+     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
+     * @param snapshot - 刚归一化出来的快照。
+     */
+    private persist;
+    /** 记录一次失败，并把状态推到 `stale` 或 `error`。 */
+    private applyFailure;
+    /** 把缓存状态推成指标。 */
+    private publishGauge;
+    /** 把缓存折成对外视图。 */
+    private toView;
+}
+//# sourceMappingURL=balance-service.d.ts.map

package/lib/services/balance-service.js

@@ -0,0 +1,220 @@
+/**
+ * 余额缓存与状态机。
+ *
+ * 职责：把「拿密钥 → 调上游 → 归一化 → 落快照」包成一次可合并的请求，并维护缓存状态。
+ * **对外永不抛错**：一切失败都变成 `view.state` 与 `view.error`。
+ * @module dsh-ds-balance/services/balance-service
+ */
+import { classify, parseRetryAfter } from '../domain/errors.js';
+import { normalize } from '../domain/normalize.js';
+import { pickBalance } from '../domain/select.js';
+import { severityOf, thresholdsFor } from '../domain/severity.js';
+import { noopMetrics } from '../ports/metrics.js';
+import { accountTag8, computeAccountTag } from './account-tag.js';
+/** 余额缓存与状态机。 */
+export class BalanceService {
+    options;
+    metrics;
+    snapshot = null;
+    state = 'empty';
+    error = null;
+    failures = 0;
+    retryAfterMs = null;
+    inflight = null;
+    /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
+    persistWarned = false;
+    constructor(options) {
+        this.options = options;
+        this.metrics = options.metrics ?? noopMetrics;
+    }
+    /** 当前状态切片，供调度与健康检查使用。 */
+    status() {
+        return {
+            state: this.state,
+            errorCode: this.error?.code ?? null,
+            consecutiveFailures: this.failures,
+            hasSnapshot: this.snapshot !== null,
+            serverRefreshSeconds: this.options.config.current().serverRefreshSeconds,
+            retryAfterMs: this.retryAfterMs,
+            lastSuccessAt: this.snapshot?.fetchedAt ?? null,
+        };
+    }
+    /**
+     * 当前账本标识的前 8 位；还没有快照时是 `null`。
+     *
+     * **只回前 8 位**：完整 tag 是账本作用域标识，没有对外的理由。
+     */
+    accountTag8() {
+        const tag = this.snapshot?.accountTag;
+        return tag === undefined ? null : accountTag8(tag);
+    }
+    /**
+     * 从存储恢复最近快照（挂载时调一次）。
+     *
+     * **按 `accountTag` 过滤**：凭据轮换后 tag 变了，旧快照视为不存在，不混用。
+     * 没有密钥可算 tag 时静默跳过。
+     */
+    async restore() {
+        try {
+            const apiKey = await this.options.keys.resolve();
+            const accountTag = computeAccountTag(this.options.salt, apiKey);
+            const stored = await this.options.store.loadLatestSnapshot(accountTag);
+            if (stored === null)
+                return;
+            this.snapshot = stored;
+            this.state = this.withinWindow() ? 'ok' : 'stale';
+            this.publishGauge();
+        }
+        catch (error) {
+            this.options.logger?.debug('ds-balance: no snapshot restored', { error: describe(error) });
+        }
+    }
+    /**
+     * 取当前视图。
+     *
+     * 有在飞的请求就合并；不 force 且未过期就返回缓存；否则拉一次。
+     */
+    async getView(options = {}) {
+        if (this.inflight !== null)
+            return this.inflight;
+        if (options.force !== true && this.canServeCache())
+            return this.toView(options.currency);
+        const run = this.fetchOnce(options.currency).finally(() => { this.inflight = null; });
+        this.inflight = run;
+        return run;
+    }
+    /**
+     * 手动刷新。
+     *
+     * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     */
+    async forceRefresh(reason) {
+        const cooldownMs = this.options.config.current().manualRefreshCooldownSeconds * 1000;
+        const since = this.options.clock.now() - (this.snapshot?.fetchedAt ?? 0);
+        if (this.state === 'ok' && since < cooldownMs) {
+            this.metrics.counter('force_rejected_total');
+            this.options.logger?.debug('ds-balance: manual refresh rejected by cooldown', { reason });
+            return { triggered: false, joined: false, cooldownMs: cooldownMs - since, state: this.state };
+        }
+        if (this.inflight !== null) {
+            await this.inflight;
+            return { triggered: true, joined: true, cooldownMs: 0, state: this.state };
+        }
+        await this.getView({ force: true });
+        return { triggered: true, joined: false, cooldownMs: 0, state: this.state };
+    }
+    /** 快照是否还在 `serverRefreshSeconds` 窗口内。**只看时间，不看状态。** */
+    withinWindow() {
+        if (this.snapshot === null)
+            return false;
+        const window = this.options.config.current().serverRefreshSeconds * 1000;
+        return this.options.clock.now() - this.snapshot.fetchedAt < window;
+    }
+    /**
+     * 能否直接拿缓存顶上。
+     *
+     * 与 {@link withinWindow} 分开：`restore` 要在状态还是 `empty` 时用纯时间判据，
+     * 而这里必须要求 `ok` —— 否则一次失败之后，窗口内的旧快照会让 `getView`
+     * 永远不再重试。
+     */
+    canServeCache() {
+        return this.state === 'ok' && this.withinWindow();
+    }
+    /** 跑一次真实抓取。**所有异常都在这里被吸收。** */
+    async fetchOnce(currency) {
+        const startedAt = this.options.clock.now();
+        try {
+            const apiKey = await this.options.keys.resolve();
+            const config = this.options.config.current();
+            const raw = await this.options.client.fetchBalance({
+                baseUrl: config.baseUrl,
+                apiKey,
+                timeoutMs: this.options.config.timeoutMs(),
+            });
+            const snapshot = normalize(raw, computeAccountTag(this.options.salt, apiKey), this.options.clock.now());
+            // 落盘失败不算这次抓取失败：快照留在内存里，界面照常显示，
+            // 代价只是重启后不恢复。存储是可降级的一层。
+            await this.persist(snapshot);
+            this.snapshot = snapshot;
+            this.state = 'ok';
+            this.error = null;
+            this.failures = 0;
+            this.retryAfterMs = null;
+            this.metrics.counter('balance_fetch_total', { result: 'ok' });
+            this.metrics.histogram('balance_fetch_duration_ms', {}, this.options.clock.now() - startedAt);
+            this.publishGauge();
+            return this.toView(currency);
+        }
+        catch (error) {
+            this.applyFailure(error, startedAt);
+            return this.toView(currency);
+        }
+    }
+    /**
+     * 把快照落盘。
+     *
+     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
+     * @param snapshot - 刚归一化出来的快照。
+     */
+    async persist(snapshot) {
+        try {
+            await this.options.store.saveSnapshot(snapshot);
+        }
+        catch (error) {
+            if (this.persistWarned)
+                return;
+            this.persistWarned = true;
+            this.options.logger?.warn('ds-balance: snapshot not persisted, continuing in memory', { error: describe(error) });
+        }
+    }
+    /** 记录一次失败，并把状态推到 `stale` 或 `error`。 */
+    applyFailure(error, startedAt) {
+        const info = classify(error);
+        this.failures += 1;
+        this.error = info;
+        this.state = this.snapshot === null ? 'error' : 'stale';
+        this.retryAfterMs = retryAfterOf(error, this.options.clock.now());
+        // 只在首次失败打 warn，避免日志刷屏。
+        if (this.failures === 1) {
+            this.options.logger?.warn('ds-balance: balance fetch failed', { code: info.code });
+        }
+        this.metrics.counter('balance_fetch_total', { result: 'error' });
+        this.metrics.histogram('balance_fetch_duration_ms', {}, this.options.clock.now() - startedAt);
+        this.publishGauge();
+    }
+    /** 把缓存状态推成指标。 */
+    publishGauge() {
+        this.metrics.gauge('cache_state', { state: this.state }, 1);
+    }
+    /** 把缓存折成对外视图。 */
+    toView(currency) {
+        const config = this.options.config.current();
+        const thresholds = this.options.config.thresholds();
+        const preference = currency ?? config.displayCurrency;
+        const selected = this.snapshot === null ? null : pickBalance(this.snapshot.balances, preference);
+        return {
+            state: this.state,
+            stale: this.state === 'stale',
+            fetchedAt: this.snapshot?.fetchedAt ?? null,
+            ageMs: this.snapshot === null ? null : Math.max(0, this.options.clock.now() - this.snapshot.fetchedAt),
+            isAvailable: this.snapshot?.isAvailable ?? null,
+            balances: this.snapshot?.balances ?? [],
+            selected: selected === null ? null : { currency: selected.currency, total: selected.total },
+            severity: severityOf(selected, this.snapshot?.isAvailable ?? false, thresholdsFor(selected?.currency ?? '', thresholds)),
+            thresholds,
+            error: this.state === 'ok' ? null : this.error,
+        };
+    }
+}
+/** 从上游错误里抽 `Retry-After`；抽不到返回 `null`。 */
+function retryAfterOf(error, now) {
+    const headers = error.headers;
+    if (headers === undefined)
+        return null;
+    return parseRetryAfter(headers, now) ?? null;
+}
+/** 把未知异常压成一行。 */
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=balance-service.js.map

package/lib/services/config-service.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 配置读取。
+ *
+ * 薄封装：把设置作用域包成「现读 + 订阅」两件事，并给出派生值（阈值、超时）。
+ * **不缓存** —— 用户改设置要立刻生效。
+ * @module dsh-ds-balance/services/config-service
+ */
+import type { Currency, ThresholdPair } from '../domain/balance.js';
+import { type Config } from '../config.js';
+/** 配置来源。生产里包 `ctx.settings` 的 scope，测试里给替身。 */
+export interface ConfigSource {
+    /** 现读当前解析值。 */
+    get(): Config;
+    /** 订阅变更，返回退订函数。 */
+    watch(listener: (next: Config, previous: Config) => void): () => void;
+    /**
+     * 把补丁合并进用户层并持久化。
+     *
+     * 可选：装配里可能没有设置服务，此时配置只读。**schema 校验失败会 reject**，
+     * 调用方要把它翻成 `422`。
+     */
+    update?(patch: Record<string, unknown>): Promise<void>;
+}
+/** 构造参数。 */
+export interface ConfigServiceOptions {
+    source: ConfigSource;
+    /** 环境变量表；默认 `process.env`。超时**每次现读**，改完立刻生效。 */
+    env?: Record<string, string | undefined>;
+}
+/** 配置读取与派生值。 */
+export declare class ConfigService {
+    private readonly source;
+    private readonly env;
+    constructor(options: ConfigServiceOptions);
+    /** 现读整份配置。 */
+    current(): Config;
+    /** 订阅配置变更。 */
+    watch(listener: (next: Config, previous: Config) => void): () => void;
+    /**
+     * 写回一份配置补丁。
+     * @param patch - 字段子集；键必须已被调用方过滤过。
+     * @throws {ValidationError} 配置源只读，或 schema 拒绝了这份补丁。
+     */
+    update(patch: Record<string, unknown>): Promise<void>;
+    /** 当前生效的阈值表（按币种）。 */
+    thresholds(): Record<Currency, ThresholdPair>;
+    /** 当前生效的上游超时（毫秒）。**每次现读环境变量。** */
+    timeoutMs(): number;
+    /** 当前展示币种偏好。 */
+    displayCurrency(): string;
+}
+//# sourceMappingURL=config-service.d.ts.map

package/lib/services/config-service.js

@@ -0,0 +1,51 @@
+/**
+ * 配置读取。
+ *
+ * 薄封装：把设置作用域包成「现读 + 订阅」两件事，并给出派生值（阈值、超时）。
+ * **不缓存** —— 用户改设置要立刻生效。
+ * @module dsh-ds-balance/services/config-service
+ */
+import { ValidationError } from '../domain/errors.js';
+import { thresholdsOf } from '../domain/severity.js';
+import { resolveTimeoutMs } from '../config.js';
+/** 配置读取与派生值。 */
+export class ConfigService {
+    source;
+    env;
+    constructor(options) {
+        this.source = options.source;
+        this.env = options.env ?? process.env;
+    }
+    /** 现读整份配置。 */
+    current() {
+        return this.source.get();
+    }
+    /** 订阅配置变更。 */
+    watch(listener) {
+        return this.source.watch(listener);
+    }
+    /**
+     * 写回一份配置补丁。
+     * @param patch - 字段子集；键必须已被调用方过滤过。
+     * @throws {ValidationError} 配置源只读，或 schema 拒绝了这份补丁。
+     */
+    async update(patch) {
+        const update = this.source.update;
+        if (update === undefined)
+            throw new ValidationError('configuration store is not writable');
+        await update(patch);
+    }
+    /** 当前生效的阈值表（按币种）。 */
+    thresholds() {
+        return thresholdsOf(this.current());
+    }
+    /** 当前生效的上游超时（毫秒）。**每次现读环境变量。** */
+    timeoutMs() {
+        return resolveTimeoutMs(this.env);
+    }
+    /** 当前展示币种偏好。 */
+    displayCurrency() {
+        return this.current().displayCurrency;
+    }
+}
+//# sourceMappingURL=config-service.js.map

package/lib/services/key-resolver.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 密钥解析。
+ *
+ * 解析链（优先级从高到低）：配置 `apiKey` → `credentials.resolve(apiKeyRef)` →
+ * `process.env[apiKeyRef]` → 抛 {@link NoKeyError}。
+ *
+ * **无 credentials seam 时不抛错**：吞掉后继续往下走，让 env 层有机会接手。
+ * @module dsh-ds-balance/services/key-resolver
+ */
+import type { Credentials } from '../ports/credentials.js';
+import type { Logger } from '../ports/logger.js';
+/** 每次解析时现读的配置切片。 */
+export interface KeyResolverConfig {
+    apiKey: string;
+    apiKeyRef: string;
+}
+/** 构造参数。 */
+export interface KeyResolverOptions {
+    /** 现读配置。**不许缓存** —— 用户改了要立刻生效。 */
+    readConfig: () => KeyResolverConfig;
+    /** 凭据服务；装配里可能没有。 */
+    credentials?: Credentials | undefined;
+    /** 环境变量表；默认 `process.env`。 */
+    env?: Record<string, string | undefined>;
+    logger?: Logger | undefined;
+    /** 引用名合法性校验；默认用契约里的正则。 */
+    isValidRef?: (ref: string) => boolean;
+}
+/** 契约要求的引用名形状。 */
+export declare const CREDENTIAL_REF_PATTERN: RegExp;
+/** 解析当前可用的明文密钥。 */
+export declare class KeyResolver {
+    private readonly options;
+    constructor(options: KeyResolverOptions);
+    /**
+     * 走完整条解析链。
+     * @returns 明文密钥。**调用方负责不把它写进日志或消息。**
+     * @throws {NoKeyError} 整条链都没取到值。
+     */
+    resolve(): Promise<string>;
+}
+//# sourceMappingURL=key-resolver.d.ts.map

package/lib/services/key-resolver.js

@@ -0,0 +1,62 @@
+/**
+ * 密钥解析。
+ *
+ * 解析链（优先级从高到低）：配置 `apiKey` → `credentials.resolve(apiKeyRef)` →
+ * `process.env[apiKeyRef]` → 抛 {@link NoKeyError}。
+ *
+ * **无 credentials seam 时不抛错**：吞掉后继续往下走，让 env 层有机会接手。
+ * @module dsh-ds-balance/services/key-resolver
+ */
+import { NoKeyError } from '../domain/errors.js';
+/** 契约要求的引用名形状。 */
+export const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 把未知异常压成一行。 */
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** 解析当前可用的明文密钥。 */
+export class KeyResolver {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * 走完整条解析链。
+     * @returns 明文密钥。**调用方负责不把它写进日志或消息。**
+     * @throws {NoKeyError} 整条链都没取到值。
+     */
+    async resolve() {
+        const config = this.options.readConfig();
+        const override = config.apiKey.trim();
+        if (override !== '')
+            return override;
+        const ref = config.apiKeyRef.trim();
+        if (ref === '')
+            throw new NoKeyError('no API key: both apiKey and apiKeyRef are empty');
+        const isValid = this.options.isValidRef ?? ((value) => CREDENTIAL_REF_PATTERN.test(value));
+        if (!isValid(ref)) {
+            throw new NoKeyError(`no API key: apiKeyRef ${JSON.stringify(ref)} is not a valid credential reference`);
+        }
+        if (this.options.credentials !== undefined) {
+            try {
+                const resolved = await this.options.credentials.resolve(ref);
+                const value = (resolved?.value ?? '').trim();
+                if (value !== '')
+                    return value;
+            }
+            catch (error) {
+                // 没有 seam、引用名不存在、远程拒绝 —— 都只是「这一档没取到」，继续往下走。
+                this.options.logger?.debug('ds-balance: credentials.resolve did not yield a key, falling back to env', {
+                    ref,
+                    error: describe(error),
+                });
+            }
+        }
+        const env = this.options.env ?? process.env;
+        const fromEnv = (env[ref] ?? '').trim();
+        if (fromEnv !== '')
+            return fromEnv;
+        throw new NoKeyError(`no API key: ${ref} is not configured`);
+    }
+}
+//# sourceMappingURL=key-resolver.js.map