dsh-ds-balance 1.0.0

package/lib/services/scheduler.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 刷新调度。
+ *
+ * `setTimeout` 链而不是 `setInterval`：每一轮跑完才排下一轮，这样退避与
+ * `Retry-After` 都能生效，也不会堆积重叠的请求。
+ * @module dsh-ds-balance/services/scheduler
+ */
+import type { BalanceView } from '../domain/balance.js';
+import type { Logger } from '../ports/logger.js';
+import type { BalanceStatus, GetViewOptions } from './balance-service.js';
+/** 首拉延迟。 */
+export declare const INITIAL_DELAY_MS = 1000;
+/** 缺密钥时的快速重试间隔。 */
+export declare const NO_KEY_RETRY_MS = 5000;
+/** 指数退避的基数与上限。 */
+export declare const BASE_BACKOFF_MS = 5000;
+export declare const MAX_BACKOFF_MS = 300000;
+/** 抖动比例。 */
+export declare const JITTER_RATIO = 0.2;
+/** 延迟下限，避免忙转。 */
+export declare const MIN_DELAY_MS = 1000;
+/** 定时器抽象，测试可注入。 */
+export interface SchedulerTimers {
+    set(callback: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** 调度器需要的最小服务面。 */
+export interface SchedulerTarget {
+    getView(options?: GetViewOptions): Promise<BalanceView>;
+    status(): BalanceStatus;
+}
+/** 构造参数。 */
+export interface SchedulerOptions {
+    target: SchedulerTarget;
+    timers?: SchedulerTimers;
+    /** 随机源，抖动用。 */
+    random?: () => number;
+    /** 时刻函数，`nextRunAt` 用。 */
+    now?: () => number;
+    /** 首拉延迟覆盖，测试用。 */
+    initialDelayMs?: number;
+    logger?: Logger | undefined;
+}
+/**
+ * 加抖动：`base * (1 ± ratio)`。
+ * @param base - 基准毫秒数。
+ * @param ratio - 抖动比例。
+ * @param random - 随机源，返回 `[0, 1)`。
+ * @returns 取整后的毫秒数。
+ */
+export declare function jitter(base: number, ratio: number, random: () => number): number;
+/**
+ * 算下一轮该等多久。
+ *
+ * 优先级：上游 `Retry-After` → 缺密钥快速重试 → 失败指数退避 → 配置的刷新频率。
+ * @param status - 服务的状态切片。
+ * @param options - 随机源。
+ * @returns 毫秒数。
+ */
+export declare function nextDelayMs(status: BalanceStatus, options?: {
+    random?: () => number;
+}): number;
+/**
+ * 刷新调度器。
+ *
+ * `start` / `stop` 幂等；`stop` 之后不再排程。**必须挂在 `ctx.effect` 的 disposer 上。**
+ */
+export declare class Scheduler {
+    private readonly options;
+    private readonly timers;
+    private readonly random;
+    private readonly now;
+    private readonly initialDelayMs;
+    private handle;
+    private running;
+    private nextAt;
+    constructor(options: SchedulerOptions);
+    /** 下一轮的计划时刻；没排程时为 `null`。 */
+    nextRunAt(): number | null;
+    /** 是否在运行。 */
+    isRunning(): boolean;
+    /** 开始调度。重复调用无效。 */
+    start(): void;
+    /** 停止调度并清掉已排的那一轮。 */
+    stop(): void;
+    /** 配置或阈值变了之后重排：立刻跑一轮再按新配置继续。 */
+    reset(): void;
+    /** 排一轮。 */
+    private schedule;
+    /** 跑一轮并按状态排下一轮。 */
+    private tick;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/lib/services/scheduler.js

@@ -0,0 +1,142 @@
+/**
+ * 刷新调度。
+ *
+ * `setTimeout` 链而不是 `setInterval`：每一轮跑完才排下一轮，这样退避与
+ * `Retry-After` 都能生效，也不会堆积重叠的请求。
+ * @module dsh-ds-balance/services/scheduler
+ */
+/** 首拉延迟。 */
+export const INITIAL_DELAY_MS = 1000;
+/** 缺密钥时的快速重试间隔。 */
+export const NO_KEY_RETRY_MS = 5000;
+/** 指数退避的基数与上限。 */
+export const BASE_BACKOFF_MS = 5000;
+export const MAX_BACKOFF_MS = 300_000;
+/** 抖动比例。 */
+export const JITTER_RATIO = 0.2;
+/** 退避指数的上限，防止 `2 ** n` 溢出。 */
+const MAX_BACKOFF_EXPONENT = 10;
+/** 延迟下限，避免忙转。 */
+export const MIN_DELAY_MS = 1000;
+/** 把值夹到区间内。 */
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * 加抖动：`base * (1 ± ratio)`。
+ * @param base - 基准毫秒数。
+ * @param ratio - 抖动比例。
+ * @param random - 随机源，返回 `[0, 1)`。
+ * @returns 取整后的毫秒数。
+ */
+export function jitter(base, ratio, random) {
+    const min = base * (1 - ratio);
+    const span = base * ratio * 2;
+    return Math.floor(min + random() * span);
+}
+/**
+ * 算下一轮该等多久。
+ *
+ * 优先级：上游 `Retry-After` → 缺密钥快速重试 → 失败指数退避 → 配置的刷新频率。
+ * @param status - 服务的状态切片。
+ * @param options - 随机源。
+ * @returns 毫秒数。
+ */
+export function nextDelayMs(status, options = {}) {
+    const random = options.random ?? Math.random;
+    if (status.retryAfterMs !== null && status.retryAfterMs > 0) {
+        return clamp(status.retryAfterMs, MIN_DELAY_MS, MAX_BACKOFF_MS);
+    }
+    if (status.errorCode === 'NO_KEY' && !status.hasSnapshot) {
+        return jitter(NO_KEY_RETRY_MS, JITTER_RATIO, random);
+    }
+    if (status.state === 'error' || status.state === 'stale') {
+        const exponent = Math.min(Math.max(0, status.consecutiveFailures - 1), MAX_BACKOFF_EXPONENT);
+        return jitter(Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** exponent), JITTER_RATIO, random);
+    }
+    return jitter(Math.max(MIN_DELAY_MS, status.serverRefreshSeconds * 1000), JITTER_RATIO, random);
+}
+/** 真正的默认定时器。 */
+const defaultTimers = {
+    set: (callback, ms) => setTimeout(callback, ms),
+    clear: (handle) => { clearTimeout(handle); },
+};
+/**
+ * 刷新调度器。
+ *
+ * `start` / `stop` 幂等；`stop` 之后不再排程。**必须挂在 `ctx.effect` 的 disposer 上。**
+ */
+export class Scheduler {
+    options;
+    timers;
+    random;
+    now;
+    initialDelayMs;
+    handle = null;
+    running = false;
+    nextAt = null;
+    constructor(options) {
+        this.options = options;
+        this.timers = options.timers ?? defaultTimers;
+        this.random = options.random ?? Math.random;
+        this.now = options.now ?? (() => Date.now());
+        this.initialDelayMs = options.initialDelayMs ?? INITIAL_DELAY_MS;
+    }
+    /** 下一轮的计划时刻；没排程时为 `null`。 */
+    nextRunAt() {
+        return this.nextAt;
+    }
+    /** 是否在运行。 */
+    isRunning() {
+        return this.running;
+    }
+    /** 开始调度。重复调用无效。 */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.schedule(this.initialDelayMs);
+    }
+    /** 停止调度并清掉已排的那一轮。 */
+    stop() {
+        this.running = false;
+        if (this.handle !== null) {
+            this.timers.clear(this.handle);
+            this.handle = null;
+        }
+        this.nextAt = null;
+    }
+    /** 配置或阈值变了之后重排：立刻跑一轮再按新配置继续。 */
+    reset() {
+        this.stop();
+        this.running = true;
+        this.schedule(0);
+    }
+    /** 排一轮。 */
+    schedule(delay) {
+        if (!this.running)
+            return;
+        this.nextAt = this.now() + delay;
+        this.handle = this.timers.set(() => { void this.tick(); }, delay);
+    }
+    /** 跑一轮并按状态排下一轮。 */
+    async tick() {
+        this.handle = null;
+        this.nextAt = null;
+        if (!this.running)
+            return;
+        try {
+            await this.options.target.getView({ force: true });
+        }
+        catch (error) {
+            // 服务承诺永不抛错；这里是防御，不让调度链断掉。
+            this.options.logger?.error('ds-balance: scheduler tick threw', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (!this.running)
+            return;
+        this.schedule(nextDelayMs(this.options.target.status(), { random: this.random }));
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/lib/types/client/api-types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 后端契约类型。本阶段不实现后端，这些形状只用来约束 mock 数据。
+ * @module dsh-ds-balance/client/api-types
+ */
+/** 余额数据的状态维度。 */
+export type BalanceState = 'empty' | 'ok' | 'stale' | 'error';
+/** 颜色严重度维度。前端只做机械映射，不比较金额。 */
+export type Severity = 'ok' | 'warn' | 'critical' | 'unavailable' | 'unknown';
+/** 估算来源。第一版 UI 不消费。 */
+export type UsageSource = 'blended' | 'balance-observed' | 'projection';
+/** 单个币种的余额。金额一律是字符串。 */
+export interface BalanceInfo {
+    currency: string;
+    total: string;
+    granted: string;
+    toppedUp: string;
+}
+/** 今日用量。第一版 UI 不消费，保留以维持契约完整。 */
+export interface TodayUsage {
+    value: string;
+    currency: string;
+    source: UsageSource;
+    confidence: string;
+    needsReview: boolean;
+    range: [string, string] | null;
+}
+/** 后端错误。 */
+export interface BalanceError {
+    code: string;
+    message: string;
+}
+/** `GET /api/v1/balance` 的响应。 */
+export interface BalanceResponse {
+    requestId: string;
+    schemaVersion: number;
+    state: BalanceState;
+    stale: boolean;
+    fetchedAt: number;
+    ageMs: number;
+    isAvailable: boolean;
+    accountTag8: string;
+    balances: BalanceInfo[];
+    selected: {
+        currency: string;
+        total: string;
+    } | null;
+    severity: Severity;
+    thresholds: Record<string, {
+        warn: string;
+        critical: string;
+    }>;
+    todayUsage: TodayUsage | null;
+    error: BalanceError | null;
+}

package/lib/types/client/data.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 数据层：向后端要余额。
+ *
+ * 端点由宿主半边的 `ctx.connection.fetch` 注册，物理载体**已做完信任与浏览器
+ * 鉴权**，所以浏览器这边只是同源 `fetch`，不带任何自己的凭据。
+ *
+ * **本模块不缓存、不合并、不排程**：节奏归调用方（`SidebarBalance` 的轮询与
+ * 手动刷新），这里只负责一次往返与两件事 —— 把 `displayCurrency` 作为查询参数
+ * 传过去、把失败翻成可展示的错误态。
+ * @module dsh-ds-balance/client/data
+ */
+import type { BalanceResponse } from './api-types.ts';
+/** 余额端点。路径与宿主半边逐字一致，不带尾随斜杠。 */
+export declare const BALANCE_PATH = "/api/v1/balance";
+/** 手动刷新端点。 */
+export declare const REFRESH_PATH = "/api/v1/balance/refresh";
+/** 配置读端点。界面只从这里取「凭据可不可写」这一件事。 */
+export declare const CONFIG_PATH = "/api/v1/config";
+/** 可替换的 fetch，便于测试注入。 */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * 凭据的只读描述。
+ *
+ * 与宿主的线上形状同构，也逐字对齐官方 `describe()`：**没有装值的槽**。
+ */
+export interface CredentialInfo {
+    ref: string;
+    configured: boolean;
+    source: string | null;
+    writable: boolean;
+}
+/** `GET /api/v1/config` 里本插件消费的那部分。 */
+export interface ConfigResponse {
+    config: Record<string, unknown>;
+    /** 已配置时是固定长度的星号串；**不含密钥的任何片段**。 */
+    apiKeyMasked: string;
+    /** 凭据端口缺席或读失败时是 `null`。 */
+    credential: CredentialInfo | null;
+    timeoutMs: number;
+}
+/** `POST /api/v1/balance/refresh` 的响应。 */
+export interface RefreshResult {
+    triggered: boolean;
+    joined: boolean;
+    cooldownMs: number;
+    state: string;
+}
+/** 端点拿不到、或回的不是 JSON 时用的错误码。 */
+export declare const UNREACHABLE_CODE = "PLUGIN_UNREACHABLE";
+/**
+ * 「还没拿到数据」的占位视图。
+ *
+ * 空态而不是错误态：首拉还没回来时不该先闪一下「读取失败」。
+ * @returns 契约形状的响应。
+ */
+export declare function pendingView(): BalanceResponse;
+/**
+ * 「拿不到数据」的视图。
+ *
+ * 只在**一次都没成功过**的时候用；已经有数据时宁可继续显示旧值 ——
+ * 后端自己的 `state: stale` 才是「数据过期」的权威表达。
+ * @param message - 面向用户的一句话。
+ * @returns 契约形状的响应。
+ */
+export declare function unreachableView(message: string): BalanceResponse;
+/**
+ * 读一次余额。
+ *
+ * `displayCurrency` **总是**作为查询参数传出去，包括 `auto` —— 后端的挑选规则
+ * 把 `auto` 当作「不指定」，所以传它不等于替后端做决定。
+ * @param options - 显示币种、可注入的 fetch 与取消信号。
+ * @returns 后端响应。
+ * @throws 端点不可达、非 2xx 或响应不是 JSON。
+ */
+export declare function requestBalance(options: {
+    currency: string;
+    fetchImpl?: FetchLike;
+    signal?: AbortSignal;
+}): Promise<BalanceResponse>;
+/**
+ * 读一次插件配置。
+ *
+ * 只为拿 `credential`：界面靠 `writable` 决定凭据字段是「可编辑」还是
+ * 「由启动环境提供（只读）」。**响应里没有密钥**，掩码是固定长度的星号串。
+ * @param options - 可注入的 fetch。
+ * @returns 配置响应里本插件消费的那部分。
+ * @throws 端点不可达、非 2xx 或响应不是 JSON。
+ */
+export declare function requestConfig(options?: {
+    fetchImpl?: FetchLike;
+}): Promise<ConfigResponse>;
+/**
+ * 触发一次手动刷新。
+ *
+ * 后端的冷却还没过时它回 `triggered: false`，那是正常结果而不是错误。
+ * @param options - 刷新原因与可注入的 fetch。
+ * @returns 后端的刷新结果。
+ * @throws 端点不可达、非 2xx 或响应不是 JSON。
+ */
+export declare function requestRefresh(options?: {
+    reason?: string;
+    fetchImpl?: FetchLike;
+}): Promise<RefreshResult>;

package/lib/types/client/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 浏览器半边入口：注册词典、设置卡片与左下角条目。
+ *
+ * 这两半各占一个 slot，互不依赖；设置卡片的位置由宿主 `installSection` 与
+ * 本文件注册的 `settings.plugin.item` 用同一个命名空间配对决定。
+ * @module dsh-ds-balance/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import './sidebar/footer-stack.module.css';
+/** 设置命名空间：与宿主 `SETTINGS_NAMESPACE` 逐字一致。 */
+export declare const SETTINGS_NAMESPACE = "ds-balance";
+/**
+ * 运行时服务门禁：删任何一项都会让 `apply` 静默不跑。
+ * 这里只需要 slot、词典与设置作用域三个服务。
+ */
+export declare const inject: string[];
+/** 挂载两半。 */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 本地化词典。`zh` 是键集真源，`en` 用 `Record<LocaleKey, string>` 做编译期完整性检查。
+ * @module dsh-ds-balance/client/locales
+ */
+/** 词典命名空间，必须与 slot 注册项的 `locale` 字段一致。 */
+export declare const NS = "ds-balance";
+/** 中文词典（键集真源）。 */
+export declare const zh: {
+    readonly 'sidebar.label': "DeepSeek 余额";
+    readonly 'sidebar.aria.balance': "DeepSeek 余额";
+    readonly 'sidebar.aria.ring': "DeepSeek 余额状态";
+    readonly 'sidebar.aria.refresh': "刷新余额";
+    readonly 'sidebar.aria.mismatch': "显示的币种与你选择的不一致";
+    readonly 'popover.title': "账户余额";
+    readonly 'popover.total': "余额";
+    readonly 'popover.granted': "赠送";
+    readonly 'popover.toppedUp': "充值";
+    readonly 'popover.updated': "{value}前";
+    readonly 'popover.updated.justNow': "刚刚更新";
+    readonly 'popover.refreshing': "刷新中";
+    readonly 'popover.cooldown': "{value} 秒后可再次刷新";
+    readonly 'popover.mismatch': "未找到 {wanted} 余额，当前显示 {shown}";
+    readonly 'popover.action.useShown': "改用 {shown}";
+    readonly 'popover.action.openSettings': "去设置";
+    readonly 'state.unavailable': "账户不可用";
+    readonly 'state.stale': "数据已过期";
+    readonly 'state.error': "读取失败";
+    readonly 'state.empty': "尚未配置";
+    readonly 'state.noKey': "尚未填写 API Key";
+    readonly 'state.noBalance': "暂无余额";
+    readonly 'settings.title': "DeepSeek 余额";
+    readonly 'settings.description': "配置账户连接、刷新节奏与预警阈值。";
+    readonly 'settings.group.connection': "连接";
+    readonly 'settings.group.refresh': "刷新";
+    readonly 'settings.group.display': "展示";
+    readonly 'settings.group.thresholds': "阈值";
+    readonly 'settings.field.apiKey': "API 密钥";
+    readonly 'settings.field.apiKeyRef': "API 密钥引用名";
+    readonly 'settings.field.baseUrl': "API 地址";
+    readonly 'settings.field.serverRefreshSeconds': "服务端刷新频率（秒）";
+    readonly 'settings.field.clientPollSeconds': "客户端轮询频率（秒）";
+    readonly 'settings.field.manualRefreshCooldownSeconds': "手动刷新冷却（秒）";
+    readonly 'settings.field.displayCurrency': "显示币种";
+    readonly 'settings.field.cnyWarn': "CNY 预警";
+    readonly 'settings.field.cnyCritical': "CNY 告急";
+    readonly 'settings.field.usdWarn': "USD 预警";
+    readonly 'settings.field.usdCritical': "USD 告急";
+    readonly 'settings.hint.apiKey': "留空则改用引用名从凭据存储读取。";
+    readonly 'settings.hint.apiKeyRef': "凭据存储里的条目名；非空时优先于 API Key。";
+    readonly 'settings.hint.baseUrl': "官方端点；使用代理或镜像时修改。";
+    readonly 'settings.hint.displayCurrency': "所选币种不存在时，回落到账户实际持有的币种。";
+    readonly 'settings.hint.number': "请填数字；留空表示使用默认值。";
+    readonly 'settings.hint.threshold': "后端判定；界面颜色跟随返回的严重度。";
+    readonly 'settings.hint.thresholdPair': "告急值必须低于预警值";
+    readonly 'settings.hint.serverRefreshSeconds': "访问官方接口的间隔。";
+    readonly 'settings.hint.clientPollSeconds': "刷新显示的间隔；只读本地缓存，不访问上游。";
+    readonly 'settings.hint.manualRefreshCooldownSeconds': "两次手动刷新之间的最短间隔。";
+    readonly 'settings.currency.auto': "自动（跟随账户）";
+    readonly 'settings.credential.envLocked': "已由启动环境提供";
+    readonly 'settings.hint.credential.env': "启动环境提供，只读。";
+    readonly 'settings.hint.credential.configured': "不写入设置文件。留空表示保持当前密钥。";
+    readonly 'settings.hint.credential.notConfigured': "尚未配置。";
+    readonly 'settings.hint.credential.overridden': "使用自定义设置里的值，忽略继承。";
+    readonly 'settings.group.customized': "自定义设置";
+    readonly 'settings.test': "测试连接";
+    readonly 'settings.testing': "测试中…";
+    readonly 'settings.test.ok': "连接正常。";
+    readonly 'settings.test.fail': "连接失败：{message}";
+    readonly 'settings.save': "保存";
+    readonly 'settings.saving': "保存中…";
+    readonly 'settings.discard': "放弃修改";
+    readonly 'settings.failed': "保存失败，请重试。";
+    readonly 'settings.readOnly': "当前配置只读，无法保存修改。";
+    readonly 'settings.unsaved': "未保存";
+    readonly 'settings.invalid': "请检查标红的字段。";
+    readonly 'settings.configured': "已配置";
+    readonly 'settings.notConfigured': "未配置";
+    readonly 'settings.overridden': "已覆盖";
+    readonly 'settings.reset': "重置";
+    readonly 'settings.invalidNumber': "请填数字；留空表示使用默认值。";
+    readonly 'settings.hint.refreshAdvanced': "不常改：默认值适用于大多数情况。";
+    readonly 'settings.currencyMismatch': "当前账户无 {wanted} 余额，实际显示 {shown}";
+    readonly 'dev.title': "开发场景";
+    readonly 'dev.hint': "仅用于 UI 开发；不影响真实配置。";
+};
+/** 词典键。 */
+export type LocaleKey = keyof typeof zh;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'ds-balance': LocaleKey;
+    }
+}
+/** 英文词典。缺键会在编译期报错。 */
+export declare const en: Record<LocaleKey, string>;
+/** 取词典。未知语言回落英文。 */
+export declare function dictionaryFor(language: string): Record<LocaleKey, string>;
+/** 极简插值：把 `{name}` 替换成实参。 */
+export declare function interpolate(template: string, params: Record<string, string>): string;

package/lib/types/client/mock/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * mock 场景解析与切换。
+ *
+ * **默认走真实端点**：只有 URL 参数或 localStorage 明确选过场景时才使用 mock，
+ * 否则插件在真机上会永远显示 demo 数据。带 `?dsb=live` 打开会清掉已存的选择。
+ *
+ * 任何一步失败都静默回落到下一档：mock 层不允许把页面搞崩。
+ * @module dsh-ds-balance/client/mock
+ */
+import type { BalanceResponse } from '../api-types.ts';
+import { type ScenarioKey } from './scenarios.ts';
+/** URL 查询参数名。 */
+export declare const SCENARIO_PARAM = "dsb";
+/** 开发模式参数名：出现即显示场景切换器。 */
+export declare const DEV_PARAM = "dsb-dev";
+/** `?dsb=` 的这个取值表示「回到真实端点」，并顺手清掉已存的场景。 */
+export declare const LIVE_PARAM_VALUE = "live";
+/**
+ * 当前生效的 mock 场景键；**该走真实端点时返回 `null`**。
+ *
+ * 这是唯一会写 localStorage 的读入口：`?dsb=live` 会顺手把已存的选择清掉。
+ * @returns 场景键，或 `null` 表示用真实端点。
+ */
+export declare function resolveScenario(): ScenarioKey | null;
+/** 当前生效的场景键；走真实端点时回落到默认场景，供切换器显示。 */
+export declare function currentScenario(): ScenarioKey;
+/** 切换场景并持久化；刷新页面后仍生效。 */
+export declare function setScenario(key: ScenarioKey): void;
+/** 是否处于开发模式（显示场景切换器）。 */
+export declare function isDevMode(): boolean;
+/** 订阅场景变化。回调立即收到一次当前值，返回退订函数。 */
+export declare function subscribeScenario(listener: (key: ScenarioKey) => void): () => void;
+/** 通知所有订阅者场景已变。 */
+export declare function notifyScenario(key: ScenarioKey): void;
+/** 取当前场景的数据快照。 */
+export declare function currentBalance(): BalanceResponse;

package/lib/types/client/mock/scenarios.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 勘察与开发用的 mock 场景。覆盖后端契约里所有状态组合。
+ *
+ * **不变量**：`selected` 由后端权威给出，所以每个场景里它要么是 `null`，
+ * 要么必须能在 `balances` 里找到同币种同金额的一条。覆写 `balances` 的场景
+ * 必须同时覆写 `selected`。这条由 `test/mock-scenarios.test.ts` 兜底。
+ * @module dsh-ds-balance/client/mock/scenarios
+ */
+import type { BalanceResponse } from '../api-types.ts';
+/** 全部场景。键即 URL 参数 `?dsb=<key>` 的取值。 */
+export declare const scenarios: {
+    /** 正常。 */
+    ok: BalanceResponse;
+    /** 余额偏低但可用。 */
+    warn: BalanceResponse;
+    /** 余额告急。 */
+    critical: BalanceResponse;
+    /** 账户不可用（余额耗尽 / 欠费）。 */
+    unavailable: BalanceResponse;
+    /** 有旧值但本次刷新失败。 */
+    stale: BalanceResponse;
+    /** 无值失败。 */
+    error: BalanceResponse;
+    /** 未配置。 */
+    empty: BalanceResponse;
+    /** 未配置且带 NO_KEY 错误。 */
+    noKey: BalanceResponse;
+    /** 多币种。`selected` 显式写出，不靠 `make()` 的默认值兜。 */
+    multiCurrency: BalanceResponse;
+    /**
+     * 选定了账户里没有的币种（USD），账户只有 CNY。
+     *
+     * 不匹配由「`selected.currency` 与设置里的显示币种不等」判定 —— 所以场景本身
+     * 只需要保证 `selected` 是账户里真实存在的那个币种，剩下的交给设置值。
+     */
+    currencyMismatch: BalanceResponse;
+    /** 账户完全没有余额。 */
+    noBalanceAtAll: BalanceResponse;
+    /** 今日用量缺失（第一版 UI 不消费，用于契约回归）。 */
+    usageMissing: BalanceResponse;
+    /** 今日用量需复核（第一版 UI 不消费，用于契约回归）。 */
+    usageNeedsReview: BalanceResponse;
+};
+/** 场景键。 */
+export type ScenarioKey = keyof typeof scenarios;
+/** 场景键清单，供开发切换器使用。 */
+export declare const scenarioKeys: ScenarioKey[];
+/** 默认场景。 */
+export declare const defaultScenario: ScenarioKey;
+/** 运行时判断一个字符串是不是已知场景键。 */
+export declare function isScenarioKey(value: string): value is ScenarioKey;