dsh-ds-balance 1.0.0

package/lib/config.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 插件配置：schemastery schema、常量与派生值。
+ *
+ * 字段名与 [UI 侧契约与移交](../docs/ui-handoff.md) 第六节逐字一致，共 **11** 个。
+ * `timeoutMs` **不在 schema 里**：它是常量加环境变量覆盖，UI 不暴露。
+ * @module dsh-ds-balance/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** 设置命名空间：与浏览器半边逐字一致，是两半的配对键。 */
+export declare const SETTINGS_NAMESPACE = "ds-balance";
+/** `displayCurrency` 的「跟随账户」取值。 */
+export declare const CURRENCY_AUTO = "auto";
+/** 官方凭据的默认引用名。与 `llm-deepseek` 的默认逐字相同。 */
+export declare const DEFAULT_API_KEY_REF = "DEEPSEEK_API_KEY";
+/** 超时常量。UI 不暴露，改环境变量即可。 */
+export declare const DEFAULT_TIMEOUT_MS = 8000;
+/** 覆盖超时的环境变量名。 */
+export declare const TIMEOUT_ENV = "DS_BALANCE_TIMEOUT_MS";
+/** 超时的合法区间。 */
+export declare const TIMEOUT_RANGE: {
+    readonly min: 1000;
+    readonly max: 60000;
+};
+/** 插件配置。 */
+export interface Config {
+    /** DeepSeek API Key。**用户显式覆盖**用；留空则走引用名解析。 */
+    apiKey: string;
+    /** 凭据引用名。必须匹配 `^[A-Za-z_][A-Za-z0-9_]*$`。 */
+    apiKeyRef: string;
+    /** 端点基址。**端点独立**，不继承对话适配器。 */
+    baseUrl: string;
+    /** 服务端刷新频率（秒）。 */
+    serverRefreshSeconds: number;
+    /** 客户端轮询频率（秒）。 */
+    clientPollSeconds: number;
+    /** 手动刷新冷却（秒）。 */
+    manualRefreshCooldownSeconds: number;
+    /** 展示币种；`auto` 表示跟随账户。 */
+    displayCurrency: string;
+    /** CNY 预警阈值。 */
+    cnyWarn: number;
+    /** CNY 告急阈值。 */
+    cnyCritical: number;
+    /** USD 预警阈值。 */
+    usdWarn: number;
+    /** USD 告急阈值。 */
+    usdCritical: number;
+}
+/**
+ * 配置字段名闭集。
+ *
+ * 供 `POST /api/v1/config` 过滤请求体用：不在表里的键一律 `422`，避免脏键被
+ * 悄悄写进用户层。**顺序与数量由 `test/config-fields.test.ts` 对着 schema 兜底**，
+ * 不靠人记。
+ */
+export declare const CONFIG_FIELDS: readonly ["apiKey", "apiKeyRef", "baseUrl", "serverRefreshSeconds", "clientPollSeconds", "manualRefreshCooldownSeconds", "displayCurrency", "cnyWarn", "cnyCritical", "usdWarn", "usdCritical"];
+/**
+ * 配置 schema。加载期校验，非法配置 fail loud。
+ *
+ * 阈值只在这里存储，前端不做金额比较：颜色由后端的 `severity` 决定。
+ */
+export declare const Config: z<Schemastery.ObjectS<{
+    apiKey: z<string, string>;
+    apiKeyRef: z<string, string>;
+    baseUrl: z<string, string>;
+    serverRefreshSeconds: z<number, number>;
+    clientPollSeconds: z<number, number>;
+    manualRefreshCooldownSeconds: z<number, number>;
+    displayCurrency: z<string, string>;
+    cnyWarn: z<number, number>;
+    cnyCritical: z<number, number>;
+    usdWarn: z<number, number>;
+    usdCritical: z<number, number>;
+}>, Schemastery.ObjectT<{
+    apiKey: z<string, string>;
+    apiKeyRef: z<string, string>;
+    baseUrl: z<string, string>;
+    serverRefreshSeconds: z<number, number>;
+    clientPollSeconds: z<number, number>;
+    manualRefreshCooldownSeconds: z<number, number>;
+    displayCurrency: z<string, string>;
+    cnyWarn: z<number, number>;
+    cnyCritical: z<number, number>;
+    usdWarn: z<number, number>;
+    usdCritical: z<number, number>;
+}>>;
+/** 一对阈值：同一币种内的预警与告急。 */
+export interface ThresholdPair {
+    readonly currency: string;
+    readonly warn: keyof Config;
+    readonly critical: keyof Config;
+}
+/**
+ * 阈值成对的清单。
+ *
+ * 字段名的约定是「币种代码小写 + Warn / Critical」；客户端按同一条约定把这两个字段
+ * 归成一对来判（[use-config-form.ts](client/settings/use-config-form.ts) 的 `THRESHOLD_PAIRS`）。
+ * 两边各存一份是因为**宿主与浏览器两个半体不许值导入**；约定本身由测试对着本表兜底。
+ */
+export declare const THRESHOLD_PAIRS: readonly ThresholdPair[];
+/**
+ * 跨字段校验：每个币种内 `critical` 必须**严格低于** `warn`。
+ *
+ * 挂在 `ctx.settings.register` 的 `validate` 上，不挂在 schema 上：
+ * schemastery 没有 refine / superRefine 这类跨字段钩子，而
+ * `SettingsRegisterOptions.validate` 正是为「schema 表达不了的约束」准备的 ——
+ * 它拿到的是**合并后、schema 已通过**的完整候选值，抛错即拒绝写入、什么都不落盘。
+ *
+ * **它在合并后的完整值上跑**，所以单字段写入会让中间态短暂非法；
+ * 客户端把成对的写入排过序（`orderPairWrites`），保证每一步中间态都合法。
+ *
+ * 为什么必须严格低于、不能相等：两者相等时余额恰好压线会被同时判成 warn 与 critical，
+ * 「预警」这一档就不存在了。措辞锚在**告急**上 —— 用户要调的是那个偏低的数。
+ * @param value - 合并后的完整配置。
+ * @throws {Error} 违反约束时抛出；消息指向具体币种，便于用户定位。
+ */
+export declare function validateThresholds(value: Config): void;
+/**
+ * 解析当前生效的超时。
+ *
+ * **每次请求都调用它** —— 改环境变量后立即生效，不需要重启。
+ * 越界或不可解析一律回落常量。
+ * @param env - 环境变量表；默认 `process.env`，测试可注入。
+ * @returns 毫秒数。
+ */
+export declare function resolveTimeoutMs(env?: Record<string, string | undefined>): number;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.js

@@ -0,0 +1,112 @@
+/**
+ * 插件配置：schemastery schema、常量与派生值。
+ *
+ * 字段名与 [UI 侧契约与移交](../docs/ui-handoff.md) 第六节逐字一致，共 **11** 个。
+ * `timeoutMs` **不在 schema 里**：它是常量加环境变量覆盖，UI 不暴露。
+ * @module dsh-ds-balance/config
+ */
+import z from '@deepseek-ai/schemastery';
+import { DEFAULT_BASE_URL } from './ports/deepseek-client.js';
+/** 设置命名空间：与浏览器半边逐字一致，是两半的配对键。 */
+export const SETTINGS_NAMESPACE = 'ds-balance';
+/** `displayCurrency` 的「跟随账户」取值。 */
+export const CURRENCY_AUTO = 'auto';
+/** 官方凭据的默认引用名。与 `llm-deepseek` 的默认逐字相同。 */
+export const DEFAULT_API_KEY_REF = 'DEEPSEEK_API_KEY';
+/** 超时常量。UI 不暴露，改环境变量即可。 */
+export const DEFAULT_TIMEOUT_MS = 8000;
+/** 覆盖超时的环境变量名。 */
+export const TIMEOUT_ENV = 'DS_BALANCE_TIMEOUT_MS';
+/** 超时的合法区间。 */
+export const TIMEOUT_RANGE = { min: 1000, max: 60_000 };
+/**
+ * 配置字段名闭集。
+ *
+ * 供 `POST /api/v1/config` 过滤请求体用：不在表里的键一律 `422`，避免脏键被
+ * 悄悄写进用户层。**顺序与数量由 `test/config-fields.test.ts` 对着 schema 兜底**，
+ * 不靠人记。
+ */
+export const CONFIG_FIELDS = [
+    'apiKey',
+    'apiKeyRef',
+    'baseUrl',
+    'serverRefreshSeconds',
+    'clientPollSeconds',
+    'manualRefreshCooldownSeconds',
+    'displayCurrency',
+    'cnyWarn',
+    'cnyCritical',
+    'usdWarn',
+    'usdCritical',
+];
+/**
+ * 配置 schema。加载期校验，非法配置 fail loud。
+ *
+ * 阈值只在这里存储，前端不做金额比较：颜色由后端的 `severity` 决定。
+ */
+export const Config = z.object({
+    apiKey: z.string().role('secret').default(''),
+    apiKeyRef: z.string().role('credential-ref').default(DEFAULT_API_KEY_REF),
+    baseUrl: z.string().default(DEFAULT_BASE_URL),
+    serverRefreshSeconds: z.natural().min(10).max(3600).default(60),
+    clientPollSeconds: z.natural().min(5).max(600).default(30),
+    manualRefreshCooldownSeconds: z.natural().min(0).max(600).default(30),
+    displayCurrency: z.string().default(CURRENCY_AUTO),
+    cnyWarn: z.number().min(0).default(10),
+    cnyCritical: z.number().min(0).default(5),
+    usdWarn: z.number().min(0).default(2),
+    usdCritical: z.number().min(0).default(1),
+});
+/**
+ * 阈值成对的清单。
+ *
+ * 字段名的约定是「币种代码小写 + Warn / Critical」；客户端按同一条约定把这两个字段
+ * 归成一对来判（[use-config-form.ts](client/settings/use-config-form.ts) 的 `THRESHOLD_PAIRS`）。
+ * 两边各存一份是因为**宿主与浏览器两个半体不许值导入**；约定本身由测试对着本表兜底。
+ */
+export const THRESHOLD_PAIRS = [
+    { currency: 'CNY', warn: 'cnyWarn', critical: 'cnyCritical' },
+    { currency: 'USD', warn: 'usdWarn', critical: 'usdCritical' },
+];
+/**
+ * 跨字段校验：每个币种内 `critical` 必须**严格低于** `warn`。
+ *
+ * 挂在 `ctx.settings.register` 的 `validate` 上，不挂在 schema 上：
+ * schemastery 没有 refine / superRefine 这类跨字段钩子，而
+ * `SettingsRegisterOptions.validate` 正是为「schema 表达不了的约束」准备的 ——
+ * 它拿到的是**合并后、schema 已通过**的完整候选值，抛错即拒绝写入、什么都不落盘。
+ *
+ * **它在合并后的完整值上跑**，所以单字段写入会让中间态短暂非法；
+ * 客户端把成对的写入排过序（`orderPairWrites`），保证每一步中间态都合法。
+ *
+ * 为什么必须严格低于、不能相等：两者相等时余额恰好压线会被同时判成 warn 与 critical，
+ * 「预警」这一档就不存在了。措辞锚在**告急**上 —— 用户要调的是那个偏低的数。
+ * @param value - 合并后的完整配置。
+ * @throws {Error} 违反约束时抛出；消息指向具体币种，便于用户定位。
+ */
+export function validateThresholds(value) {
+    for (const pair of THRESHOLD_PAIRS) {
+        const warn = value[pair.warn];
+        const critical = value[pair.critical];
+        if (critical < warn)
+            continue;
+        throw new Error(`${pair.currency} 告急必须低于预警（当前 预警 ${String(warn)} / 告急 ${String(critical)}）`);
+    }
+}
+/**
+ * 解析当前生效的超时。
+ *
+ * **每次请求都调用它** —— 改环境变量后立即生效，不需要重启。
+ * 越界或不可解析一律回落常量。
+ * @param env - 环境变量表；默认 `process.env`，测试可注入。
+ * @returns 毫秒数。
+ */
+export function resolveTimeoutMs(env = process.env) {
+    const raw = Number(env[TIMEOUT_ENV]);
+    if (!Number.isFinite(raw))
+        return DEFAULT_TIMEOUT_MS;
+    if (raw < TIMEOUT_RANGE.min || raw > TIMEOUT_RANGE.max)
+        return DEFAULT_TIMEOUT_MS;
+    return Math.trunc(raw);
+}
+//# sourceMappingURL=config.js.map

package/lib/domain/balance.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 余额领域类型。
+ *
+ * 这里定义的是**契约形状**：金额一律 `bigint` 最小单位，序列化时才变字符串。
+ * @module dsh-ds-balance/domain/balance
+ */
+import type { ErrorInfo } from './errors.js';
+import type { Units } from './money.js';
+/** 币种代码，例如 `CNY` / `USD`。 */
+export type Currency = string;
+/** 缓存状态。闭集。 */
+export type CacheState = 'empty' | 'ok' | 'stale' | 'error';
+/** 颜色严重度。闭集，前端只做机械映射。 */
+export type Severity = 'ok' | 'warn' | 'critical' | 'unavailable' | 'unknown';
+/** 单个币种的余额。 */
+export interface BalanceInfo {
+    currency: Currency;
+    total: Units;
+    granted: Units;
+    toppedUp: Units;
+}
+/** 一次成功抓取的不可变快照。 */
+export interface BalanceSnapshot {
+    /** 快照标识，单调可排序。 */
+    snapshotId: string;
+    /** 账本作用域标识：HMAC(serverSalt, apiKey) 前缀，不含明文。 */
+    accountTag: string;
+    /** 抓取时刻（毫秒）。 */
+    fetchedAt: number;
+    /** 上游 `is_available`。 */
+    isAvailable: boolean;
+    /** 全币种余额。 */
+    balances: BalanceInfo[];
+    /** 数据来源。 */
+    source: 'deepseek-http';
+    /** 原始响应，审计用。 */
+    raw: unknown;
+}
+/** 一个币种的预警 / 告急阈值。 */
+export interface ThresholdPair {
+    warn: Units;
+    critical: Units;
+}
+/** 给前端的余额视图。 */
+export interface BalanceView {
+    state: CacheState;
+    stale: boolean;
+    fetchedAt: number | null;
+    ageMs: number | null;
+    isAvailable: boolean | null;
+    balances: BalanceInfo[];
+    selected: {
+        currency: Currency;
+        total: Units;
+    } | null;
+    severity: Severity;
+    thresholds: Record<Currency, ThresholdPair>;
+    error: ErrorInfo | null;
+}
+/** 上游 `GET /user/balance` 的原始响应形状。字段名保持上游拼写。 */
+export interface RawBalanceResponse {
+    is_available: boolean;
+    balance_infos: Array<{
+        currency: string;
+        total_balance: string;
+        granted_balance: string;
+        topped_up_balance: string;
+    }>;
+}
+//# sourceMappingURL=balance.d.ts.map

package/lib/domain/balance.js

@@ -0,0 +1,8 @@
+/**
+ * 余额领域类型。
+ *
+ * 这里定义的是**契约形状**：金额一律 `bigint` 最小单位，序列化时才变字符串。
+ * @module dsh-ds-balance/domain/balance
+ */
+export {};
+//# sourceMappingURL=balance.js.map

package/lib/domain/errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 领域错误与错误分类。
+ *
+ * 宿主半边的对外错误一律映射成 {@link ErrorInfo}：合约规定余额错误走
+ * `200 + state: error`，HTTP 层不得把异常抛出去让宿主包成 500。
+ * @module dsh-ds-balance/domain/errors
+ */
+/** 对外可见的错误码闭集。 */
+export type ErrorCode = 'NO_KEY' | 'NO_NETWORK' | 'UPSTREAM_TIMEOUT' | 'UPSTREAM_401' | 'UPSTREAM_402' | 'UPSTREAM_422' | 'UPSTREAM_429' | 'UPSTREAM_4XX' | 'UPSTREAM_5XX' | 'UPSTREAM_503' | 'PARSE_ERROR' | 'SHAPE_ERROR' | 'COOLDOWN' | 'CONFLICT' | 'VALIDATION' | 'UNAUTHORIZED' | 'NOT_FOUND' | 'STORAGE_ERROR';
+/** 跨线传给前端的错误形状。 */
+export interface ErrorInfo {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}
+/** 构造 {@link AppError} 的可选参数。 */
+export interface AppErrorOptions {
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/** 所有本插件错误的基类：带错误码与可重试标记。 */
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    readonly retryable: boolean;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, options?: AppErrorOptions);
+}
+/** 没有可用的 API Key。解析链全空时抛这个。 */
+export declare class NoKeyError extends AppError {
+    constructor(message?: string);
+}
+/** 请求超时。 */
+export declare class TimeoutError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 网络不可达（DNS / 连接失败）。 */
+export declare class NetworkError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 把 HTTP 状态码映射到错误码。 */
+export declare function upstreamCodeOf(status: number): ErrorCode;
+/** 上游返回了非 2xx。 */
+export declare class UpstreamError extends AppError {
+    readonly status: number;
+    readonly headers: Headers | undefined;
+    constructor(status: number, message: string, options?: {
+        headers?: Headers;
+        cause?: unknown;
+    });
+}
+/** 金额或响应体解析失败。绝不静默归 0。 */
+export declare class ParseError extends AppError {
+    constructor(message: string, options?: AppErrorOptions);
+}
+/** 响应结构与契约不符。 */
+export declare class ShapeError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 入参或配置没通过校验。**不可重试** —— 同一份输入重放还是失败。 */
+export declare class ValidationError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 存储层失败。可重试。 */
+export declare class StorageError extends AppError {
+    constructor(message: string, options?: AppErrorOptions);
+}
+/**
+ * 解析 `Retry-After`。支持秒数与 HTTP-date 两种写法。
+ * @param headers - 上游响应头；缺失时返回 `undefined`。
+ * @param now - 当前时刻，HTTP-date 用它算差值；便于测试注入。
+ * @returns 毫秒数，或 `undefined` 表示没给出可用的提示。
+ */
+export declare function parseRetryAfter(headers: Headers | undefined, now?: number): number | undefined;
+/**
+ * 把任意异常映射成对外错误。
+ *
+ * 顺序重要：先认自己的类型，再认带 `status` 的外部错误，最后兜底。
+ * @param error - 任意抛出的值。
+ * @returns 契约里的错误形状。
+ */
+export declare function classify(error: unknown): ErrorInfo;
+//# sourceMappingURL=errors.d.ts.map

package/lib/domain/errors.js

@@ -0,0 +1,136 @@
+/**
+ * 领域错误与错误分类。
+ *
+ * 宿主半边的对外错误一律映射成 {@link ErrorInfo}：合约规定余额错误走
+ * `200 + state: error`，HTTP 层不得把异常抛出去让宿主包成 500。
+ * @module dsh-ds-balance/domain/errors
+ */
+/** 所有本插件错误的基类：带错误码与可重试标记。 */
+export class AppError extends Error {
+    code;
+    retryable;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name;
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.details = options.details;
+    }
+}
+/** 没有可用的 API Key。解析链全空时抛这个。 */
+export class NoKeyError extends AppError {
+    constructor(message = 'API key not configured') {
+        super('NO_KEY', message);
+    }
+}
+/** 请求超时。 */
+export class TimeoutError extends AppError {
+    constructor(message = 'upstream timeout', options = {}) {
+        super('UPSTREAM_TIMEOUT', message, { ...options, retryable: true });
+    }
+}
+/** 网络不可达（DNS / 连接失败）。 */
+export class NetworkError extends AppError {
+    constructor(message = 'network unreachable', options = {}) {
+        super('NO_NETWORK', message, { ...options, retryable: true });
+    }
+}
+/** 把 HTTP 状态码映射到错误码。 */
+export function upstreamCodeOf(status) {
+    switch (status) {
+        case 401: return 'UPSTREAM_401';
+        case 402: return 'UPSTREAM_402';
+        case 422: return 'UPSTREAM_422';
+        case 429: return 'UPSTREAM_429';
+        case 503: return 'UPSTREAM_503';
+        default:
+            if (status >= 500)
+                return 'UPSTREAM_5XX';
+            return 'UPSTREAM_4XX';
+    }
+}
+/** 上游返回了非 2xx。 */
+export class UpstreamError extends AppError {
+    status;
+    headers;
+    constructor(status, message, options = {}) {
+        super(upstreamCodeOf(status), message, {
+            retryable: status >= 500 || status === 429,
+            cause: options.cause,
+        });
+        this.status = status;
+        this.headers = options.headers;
+    }
+}
+/** 金额或响应体解析失败。绝不静默归 0。 */
+export class ParseError extends AppError {
+    constructor(message, options = {}) {
+        super('PARSE_ERROR', message, options);
+    }
+}
+/** 响应结构与契约不符。 */
+export class ShapeError extends AppError {
+    constructor(message = 'response shape mismatch', options = {}) {
+        super('SHAPE_ERROR', message, options);
+    }
+}
+/** 入参或配置没通过校验。**不可重试** —— 同一份输入重放还是失败。 */
+export class ValidationError extends AppError {
+    constructor(message = 'validation failed', options = {}) {
+        super('VALIDATION', message, options);
+    }
+}
+/** 存储层失败。可重试。 */
+export class StorageError extends AppError {
+    constructor(message, options = {}) {
+        super('STORAGE_ERROR', message, { ...options, retryable: true });
+    }
+}
+/**
+ * 解析 `Retry-After`。支持秒数与 HTTP-date 两种写法。
+ * @param headers - 上游响应头；缺失时返回 `undefined`。
+ * @param now - 当前时刻，HTTP-date 用它算差值；便于测试注入。
+ * @returns 毫秒数，或 `undefined` 表示没给出可用的提示。
+ */
+export function parseRetryAfter(headers, now = Date.now()) {
+    const raw = headers?.get('retry-after');
+    if (raw === undefined || raw === null)
+        return undefined;
+    const text = raw.trim();
+    if (text === '')
+        return undefined;
+    if (/^\d+$/.test(text)) {
+        const seconds = Number(text);
+        return Number.isFinite(seconds) ? seconds * 1000 : undefined;
+    }
+    const at = Date.parse(text);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, at - now);
+}
+/**
+ * 把任意异常映射成对外错误。
+ *
+ * 顺序重要：先认自己的类型，再认带 `status` 的外部错误，最后兜底。
+ * @param error - 任意抛出的值。
+ * @returns 契约里的错误形状。
+ */
+export function classify(error) {
+    if (error instanceof AppError) {
+        const info = { code: error.code, message: error.message, retryable: error.retryable };
+        return error.details === undefined ? info : { ...info, details: error.details };
+    }
+    if (error instanceof Error) {
+        if (error.name === 'AbortError' || error.name === 'TimeoutError') {
+            return { code: 'UPSTREAM_TIMEOUT', message: error.message, retryable: true };
+        }
+        const code = error.code;
+        if (typeof code === 'string' && /^(ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|UND_ERR)/.test(code)) {
+            return { code: 'NO_NETWORK', message: error.message, retryable: true };
+        }
+        return { code: 'STORAGE_ERROR', message: error.message, retryable: true };
+    }
+    return { code: 'STORAGE_ERROR', message: String(error), retryable: true };
+}
+//# sourceMappingURL=errors.js.map

package/lib/domain/money.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 定点金额。
+ *
+ * 全程 `bigint`，绝不经过浮点 —— 合约要求金额是字符串、比较与累加只在后端做。
+ * @module dsh-ds-balance/domain/money
+ */
+/** 1 个货币单位对应的最小单位数（8 位小数）。 */
+export declare const MONEY_SCALE = 100000000n;
+/** 契约规定的小数位数。 */
+export declare const MONEY_DECIMALS = 8;
+/** 金额的最小单位表示。 */
+export type Units = bigint;
+/**
+ * 把契约里的金额字符串解析成最小单位。
+ *
+ * 超过 {@link MONEY_DECIMALS} 位的小数**截断，不四舍五入**；解析失败抛
+ * {@link ParseError}，绝不静默归 0。
+ * @param input - 金额字符串或数字（数字会被先转成字符串）。
+ * @returns 最小单位金额。
+ * @throws {ParseError} 当文本不是十进制定点。
+ */
+export declare function parseMoney(input: string | number): Units;
+/**
+ * 把最小单位格式化成定点字符串。
+ * @param units - 最小单位金额。
+ * @param decimals - 保留几位小数，0..{@link MONEY_DECIMALS}；默认 8（给 API），UI 用 2。
+ * @returns 定点字符串，超出的位数直接截断。
+ * @throws {RangeError} 当 `decimals` 越界。
+ */
+export declare function formatMoney(units: Units, decimals?: number): string;
+/** 加法。 */
+export declare function addMoney(left: Units, right: Units): Units;
+/** 减法。 */
+export declare function subMoney(left: Units, right: Units): Units;
+/** 三路比较：-1 / 0 / 1。 */
+export declare function cmpMoney(left: Units, right: Units): -1 | 0 | 1;
+/** 是否为零。 */
+export declare function isZeroMoney(value: Units): boolean;
+//# sourceMappingURL=money.d.ts.map

package/lib/domain/money.js

@@ -0,0 +1,74 @@
+/**
+ * 定点金额。
+ *
+ * 全程 `bigint`，绝不经过浮点 —— 合约要求金额是字符串、比较与累加只在后端做。
+ * @module dsh-ds-balance/domain/money
+ */
+import { ParseError } from './errors.js';
+/** 1 个货币单位对应的最小单位数（8 位小数）。 */
+export const MONEY_SCALE = 100000000n;
+/** 契约规定的小数位数。 */
+export const MONEY_DECIMALS = 8;
+/** 只接受十进制定点：可选负号、整数部分、可选小数部分。不接受科学计数法。 */
+const MONEY_PATTERN = /^(-?)(\d+)(?:\.(\d+))?$/;
+/**
+ * 把契约里的金额字符串解析成最小单位。
+ *
+ * 超过 {@link MONEY_DECIMALS} 位的小数**截断，不四舍五入**；解析失败抛
+ * {@link ParseError}，绝不静默归 0。
+ * @param input - 金额字符串或数字（数字会被先转成字符串）。
+ * @returns 最小单位金额。
+ * @throws {ParseError} 当文本不是十进制定点。
+ */
+export function parseMoney(input) {
+    const text = String(input).trim();
+    const match = MONEY_PATTERN.exec(text);
+    if (match === null) {
+        throw new ParseError(`not a decimal amount: ${JSON.stringify(text.slice(0, 40))}`);
+    }
+    const sign = match[1] ?? '';
+    const whole = match[2] ?? '0';
+    const fraction = match[3] ?? '';
+    const scaled = (fraction + '00000000').slice(0, MONEY_DECIMALS);
+    const magnitude = BigInt(whole) * MONEY_SCALE + BigInt(scaled);
+    return sign === '-' ? -magnitude : magnitude;
+}
+/**
+ * 把最小单位格式化成定点字符串。
+ * @param units - 最小单位金额。
+ * @param decimals - 保留几位小数，0..{@link MONEY_DECIMALS}；默认 8（给 API），UI 用 2。
+ * @returns 定点字符串，超出的位数直接截断。
+ * @throws {RangeError} 当 `decimals` 越界。
+ */
+export function formatMoney(units, decimals = MONEY_DECIMALS) {
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > MONEY_DECIMALS) {
+        throw new RangeError(`decimals must be an integer in 0..${MONEY_DECIMALS}`);
+    }
+    const negative = units < 0n;
+    const magnitude = negative ? -units : units;
+    const whole = (magnitude / MONEY_SCALE).toString();
+    const fraction = (magnitude % MONEY_SCALE).toString().padStart(MONEY_DECIMALS, '0');
+    const body = decimals === 0 ? whole : `${whole}.${fraction.slice(0, decimals)}`;
+    return negative ? `-${body}` : body;
+}
+/** 加法。 */
+export function addMoney(left, right) {
+    return left + right;
+}
+/** 减法。 */
+export function subMoney(left, right) {
+    return left - right;
+}
+/** 三路比较：-1 / 0 / 1。 */
+export function cmpMoney(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+/** 是否为零。 */
+export function isZeroMoney(value) {
+    return value === 0n;
+}
+//# sourceMappingURL=money.js.map