@tokenbuddy/contracts 1.0.0 → 1.0.36

package/dist/src/upstream-balance-probe.js

@@ -0,0 +1,384 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultBalanceProbeCache = exports.BalanceProbeCache = void 0;
+exports.probeUpstreamBalance = probeUpstreamBalance;
+const DEFAULT_TIMEOUT_MS = 7000;
+const FAILURE_CACHE_TTL_MS = 30000;
+const DEFAULT_CNY_USD_RATE = 0.14;
+class BalanceProbeCache {
+    entries = new Map();
+    get(key, now) {
+        const entry = this.entries.get(key);
+        if (!entry || entry.expiresAt <= now) {
+            if (entry) {
+                this.entries.delete(key);
+            }
+            return undefined;
+        }
+        return entry.snapshot;
+    }
+    setFailure(key, snapshot, now) {
+        this.entries.set(key, {
+            snapshot,
+            expiresAt: now + FAILURE_CACHE_TTL_MS
+        });
+    }
+}
+exports.BalanceProbeCache = BalanceProbeCache;
+exports.defaultBalanceProbeCache = new BalanceProbeCache();
+async function probeUpstreamBalance(config, options = {}) {
+    const now = options.now || Date.now;
+    const fetchedAt = now();
+    const key = cacheKey(config);
+    const cache = options.cache || exports.defaultBalanceProbeCache;
+    const cached = cache.get(key, fetchedAt);
+    if (cached) {
+        return cached;
+    }
+    const plan = requestPlan(config);
+    if (!plan) {
+        const snapshot = failure("unknown", fetchedAt, 0, "unsupported upstream - configure a balance parser");
+        cache.setFailure(key, snapshot, fetchedAt);
+        return snapshot;
+    }
+    if (!config.upstreamApiKey) {
+        const snapshot = failure(plan.source, fetchedAt, 0, "missing upstreamApiKey for balance probe");
+        cache.setFailure(key, snapshot, fetchedAt);
+        return snapshot;
+    }
+    const upstreamUserId = stringValue(config.upstreamBalanceProbe?.userId) || stringValue(config.upstreamUserId);
+    if (plan.requiresUserId && !upstreamUserId) {
+        const snapshot = failure(plan.source, fetchedAt, 0, "missing upstreamUserId for newapi upstream");
+        cache.setFailure(key, snapshot, fetchedAt);
+        return snapshot;
+    }
+    try {
+        const response = await fetchWithTimeout(plan.url, {
+            method: "GET",
+            headers: requestHeaders(config.upstreamApiKey, plan.requiresUserId ? upstreamUserId : undefined)
+        }, options.fetch || fetch, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        if (!response.ok) {
+            const snapshot = failure(plan.source, fetchedAt, response.status, httpErrorMessage(response.status));
+            cache.setFailure(key, snapshot, fetchedAt);
+            return snapshot;
+        }
+        const payload = await response.json();
+        const snapshot = parseBalancePayload(payload, plan, fetchedAt, cnyUsdRate(options.cnyUsdRate));
+        if (snapshot.error) {
+            cache.setFailure(key, snapshot, fetchedAt);
+        }
+        return snapshot;
+    }
+    catch (err) {
+        const snapshot = failure(plan.source, fetchedAt, 0, `network: ${err instanceof Error ? err.message : String(err)}`);
+        cache.setFailure(key, snapshot, fetchedAt);
+        return snapshot;
+    }
+}
+function requestPlan(config) {
+    const template = balanceProbeTemplateValue(config.upstreamBalanceProbe?.template);
+    if (template === "none") {
+        return undefined;
+    }
+    const balanceUrl = stringValue(config.upstreamBalanceProbe?.url) || stringValue(config.upstreamBalanceUrl);
+    const upstreamUrl = stringValue(config.upstreamUrl);
+    if (template && template !== "auto") {
+        return explicitRequestPlan(template, balanceUrl, upstreamUrl);
+    }
+    const host = hostName(balanceUrl || upstreamUrl);
+    if (host === "api.deepseek.com") {
+        return { source: "deepseek", url: "https://api.deepseek.com/user/balance", currency: "CNY", requiresUserId: false };
+    }
+    if (host === "api.stepfun.ai" || host === "api.stepfun.com") {
+        return { source: "stepfun", url: "https://api.stepfun.com/v1/accounts", currency: "CNY", requiresUserId: false };
+    }
+    if (host === "api.siliconflow.cn" || host === "api.siliconflow.com") {
+        const currency = host.endsWith(".cn") ? "CNY" : "USD";
+        const url = host.endsWith(".cn") ? "https://api.siliconflow.cn/v1/user/info" : "https://api.siliconflow.com/v1/user/info";
+        return { source: "siliconflow", url, currency, requiresUserId: false };
+    }
+    if (host === "openrouter.ai") {
+        return { source: "openrouter", url: "https://openrouter.ai/api/v1/credits", currency: "USD", requiresUserId: false };
+    }
+    if (host === "api.novita.ai") {
+        return { source: "novita", url: "https://api.novita.ai/v3/user/balance", currency: "USD", requiresUserId: false };
+    }
+    if (balanceUrl && isUsageEndpoint(balanceUrl)) {
+        return { source: "usage_generic", url: balanceUrl, currency: "USD", requiresUserId: false };
+    }
+    if (balanceUrl) {
+        return { source: "newapi_generic", url: balanceUrl, currency: "USD", requiresUserId: true };
+    }
+    const genericUsageUrl = upstreamUrl ? usageUrl(upstreamUrl) : undefined;
+    if (genericUsageUrl) {
+        return { source: "usage_generic", url: genericUsageUrl, currency: "USD", requiresUserId: false };
+    }
+    return undefined;
+}
+function explicitRequestPlan(template, balanceUrl, upstreamUrl) {
+    if (template === "deepseek") {
+        return { source: "deepseek", url: balanceUrl || "https://api.deepseek.com/user/balance", currency: "CNY", requiresUserId: false };
+    }
+    if (template === "stepfun") {
+        return { source: "stepfun", url: balanceUrl || "https://api.stepfun.com/v1/accounts", currency: "CNY", requiresUserId: false };
+    }
+    if (template === "siliconflow") {
+        const host = hostName(balanceUrl || upstreamUrl);
+        const currency = host.endsWith(".com") ? "USD" : "CNY";
+        const url = balanceUrl || (currency === "USD" ? "https://api.siliconflow.com/v1/user/info" : "https://api.siliconflow.cn/v1/user/info");
+        return { source: "siliconflow", url, currency, requiresUserId: false };
+    }
+    if (template === "openrouter") {
+        return { source: "openrouter", url: balanceUrl || "https://openrouter.ai/api/v1/credits", currency: "USD", requiresUserId: false };
+    }
+    if (template === "novita") {
+        return { source: "novita", url: balanceUrl || "https://api.novita.ai/v3/user/balance", currency: "USD", requiresUserId: false };
+    }
+    if (template === "newapi_generic") {
+        return balanceUrl ? { source: "newapi_generic", url: balanceUrl, currency: "USD", requiresUserId: true } : undefined;
+    }
+    if (template === "usage_generic") {
+        const url = balanceUrl || (upstreamUrl ? usageUrl(upstreamUrl) : undefined);
+        return url ? { source: "usage_generic", url, currency: "USD", requiresUserId: false } : undefined;
+    }
+    return undefined;
+}
+function requestHeaders(upstreamApiKey, upstreamUserId) {
+    const headers = {
+        "Authorization": `Bearer ${upstreamApiKey}`
+    };
+    if (upstreamUserId) {
+        headers["New-Api-User"] = upstreamUserId;
+    }
+    return headers;
+}
+async function fetchWithTimeout(url, init, fetchFn, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchFn(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parseBalancePayload(payload, plan, fetchedAt, cnyRate) {
+    const object = objectValue(payload);
+    if (!object) {
+        return failure(plan.source, fetchedAt, 200, "balance response must be an object");
+    }
+    if (plan.source === "deepseek") {
+        return parseDeepSeek(object, fetchedAt, cnyRate);
+    }
+    if (plan.source === "stepfun") {
+        return amountSnapshot(numberFrom(object.balance), "CNY", "stepfun", fetchedAt, cnyRate);
+    }
+    if (plan.source === "siliconflow") {
+        return parseSiliconFlow(object, plan.currency, fetchedAt, cnyRate);
+    }
+    if (plan.source === "openrouter") {
+        return parseOpenRouter(object, fetchedAt, cnyRate);
+    }
+    if (plan.source === "novita") {
+        const availableBalance = numberFrom(object.availableBalance);
+        return amountSnapshot(availableBalance === null ? null : availableBalance / 10000, "USD", "novita", fetchedAt, cnyRate);
+    }
+    if (plan.source === "newapi_generic") {
+        return parseNewApi(object, fetchedAt, cnyRate);
+    }
+    if (plan.source === "usage_generic") {
+        return parseUsageGeneric(object, fetchedAt, cnyRate);
+    }
+    return failure("unknown", fetchedAt, 0, "unsupported upstream - configure a balance parser");
+}
+function parseDeepSeek(payload, fetchedAt, cnyRate) {
+    const infos = Array.isArray(payload.balance_infos) ? payload.balance_infos : [];
+    const first = objectValue(infos[0]);
+    const currency = currencyValue(first?.currency) || "CNY";
+    const rawAmount = numberFrom(first?.total_balance);
+    if (payload.is_available === false) {
+        return {
+            ...amountSnapshot(rawAmount, currency, "deepseek", fetchedAt, cnyRate),
+            error: { httpStatus: 200, message: "Insufficient balance" }
+        };
+    }
+    if (!first) {
+        return amountSnapshot(null, currency, "deepseek", fetchedAt, cnyRate);
+    }
+    if (rawAmount === null) {
+        return failure("deepseek", fetchedAt, 200, "missing field: balance_infos[].total_balance", currency);
+    }
+    return amountSnapshot(rawAmount, currency, "deepseek", fetchedAt, cnyRate);
+}
+function parseSiliconFlow(payload, currency, fetchedAt, cnyRate) {
+    const code = numberFrom(payload.code);
+    if (code !== null && code !== 20000) {
+        return failure("siliconflow", fetchedAt, 200, `upstream code: ${code}`, currency);
+    }
+    const data = objectValue(payload.data);
+    if (!data) {
+        return failure("siliconflow", fetchedAt, 200, "missing field: data", currency);
+    }
+    const snapshot = amountSnapshot(numberFrom(data.totalBalance), currency, "siliconflow", fetchedAt, cnyRate);
+    const status = stringValue(data.status);
+    if (status && status !== "ok") {
+        return {
+            ...snapshot,
+            error: { httpStatus: 200, message: `upstream status: ${status}` }
+        };
+    }
+    return snapshot;
+}
+function parseOpenRouter(payload, fetchedAt, cnyRate) {
+    const data = objectValue(payload.data) || payload;
+    const totalCredits = numberFrom(data.total_credits);
+    const totalUsage = numberFrom(data.total_usage);
+    if (totalCredits === null || totalUsage === null) {
+        return failure("openrouter", fetchedAt, 200, "missing field: data.total_credits or data.total_usage", "USD");
+    }
+    return amountSnapshot(Math.max(0, totalCredits - totalUsage), "USD", "openrouter", fetchedAt, cnyRate);
+}
+function parseNewApi(payload, fetchedAt, cnyRate) {
+    const data = objectValue(payload.data);
+    if (!data) {
+        return failure("newapi_generic", fetchedAt, 200, "missing field: data", "USD");
+    }
+    const quota = numberFrom(data.quota);
+    const usedQuota = numberFrom(data.used_quota);
+    if (quota === null || usedQuota === null) {
+        return failure("newapi_generic", fetchedAt, 200, "missing field: data.quota or data.used_quota", "USD");
+    }
+    return amountSnapshot((quota - usedQuota) / 500000, "USD", "newapi_generic", fetchedAt, cnyRate);
+}
+function parseUsageGeneric(payload, fetchedAt, cnyRate) {
+    const quota = objectValue(payload.quota);
+    const rawAmount = numberFrom(payload.remaining) ?? numberFrom(quota?.remaining) ?? numberFrom(payload.balance);
+    const currency = currencyValue(payload.unit) || currencyValue(quota?.unit) || "USD";
+    if (rawAmount === null) {
+        return failure("usage_generic", fetchedAt, 200, "missing field: remaining, quota.remaining, or balance", currency);
+    }
+    const snapshot = amountSnapshot(rawAmount, currency, "usage_generic", fetchedAt, cnyRate);
+    const isValid = booleanValue(payload.is_active) ?? booleanValue(payload.isValid) ?? true;
+    if (!isValid) {
+        return {
+            ...snapshot,
+            error: { httpStatus: 200, message: "upstream key is not active" }
+        };
+    }
+    return snapshot;
+}
+function amountSnapshot(rawAmount, currency, source, fetchedAt, cnyRate) {
+    return {
+        rawAmount,
+        amountUsdMicros: rawAmount === null ? null : Math.round(rawAmount * (currency === "CNY" ? cnyRate : 1) * 1000000),
+        currency,
+        source,
+        fetchedAt
+    };
+}
+function failure(source, fetchedAt, httpStatus, message, currency = null) {
+    return {
+        rawAmount: null,
+        amountUsdMicros: null,
+        currency,
+        source,
+        fetchedAt,
+        error: { httpStatus, message }
+    };
+}
+function httpErrorMessage(status) {
+    if (status === 401) {
+        return "unauthorized: check upstreamApiKey";
+    }
+    if (status === 403) {
+        return "forbidden: upstream rejected the credentials";
+    }
+    if (status === 429) {
+        return "rate limited";
+    }
+    if (status >= 500) {
+        return "upstream 5xx";
+    }
+    return `upstream http ${status}`;
+}
+function cnyUsdRate(value) {
+    if (value !== undefined && Number.isFinite(value) && value > 0) {
+        return value;
+    }
+    const envValue = Number(process.env.TB_CNY_USD_RATE);
+    return Number.isFinite(envValue) && envValue > 0 ? envValue : DEFAULT_CNY_USD_RATE;
+}
+function cacheKey(config) {
+    return [
+        stringValue(config.upstreamBalanceProbe?.template),
+        stringValue(config.upstreamBalanceProbe?.url),
+        stringValue(config.upstreamBalanceProbe?.userId),
+        stringValue(config.upstreamBalanceUrl),
+        stringValue(config.upstreamUrl),
+        stringValue(config.upstreamApiKey),
+        stringValue(config.upstreamUserId)
+    ].join("|");
+}
+function balanceProbeTemplateValue(value) {
+    return value === "auto" ||
+        value === "deepseek" ||
+        value === "stepfun" ||
+        value === "siliconflow" ||
+        value === "openrouter" ||
+        value === "novita" ||
+        value === "newapi_generic" ||
+        value === "usage_generic" ||
+        value === "none"
+        ? value
+        : undefined;
+}
+function hostName(value) {
+    if (!value) {
+        return "";
+    }
+    try {
+        return new URL(value).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return "";
+    }
+}
+function usageUrl(value) {
+    try {
+        const url = new URL(value);
+        url.pathname = "/v1/usage";
+        url.search = "";
+        url.hash = "";
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function isUsageEndpoint(value) {
+    try {
+        return new URL(value).pathname.replace(/\/+$/, "") === "/v1/usage";
+    }
+    catch {
+        return false;
+    }
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function numberFrom(value) {
+    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function currencyValue(value) {
+    return value === "USD" || value === "CNY" ? value : undefined;
+}
+//# sourceMappingURL=upstream-balance-probe.js.map

package/dist/src/upstream-balance-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-balance-probe.js","sourceRoot":"","sources":["../../src/upstream-balance-probe.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenbuddy/contracts",
-  "version": "1.0.0",
+  "version": "1.0.36",
   "description": "Shared contract models and crypto functions",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -14,4 +14,4 @@
   "devDependencies": {
     "@types/uuid": "^9.0.8"
   }
-}
+}

package/src/crypto.ts

@@ -47,22 +47,35 @@ export function decryptSm4EcbPkcs7Base64(encryptedBase64: string, sm4KeyBase64:
 }
 
 /**
- * Compute md5 hex digest of a string (indicator).
+ * 计算资源 slug 的 MD5 摘要（hex 编码）。
+ * 用作 Clawtip 支付的 indicator 字段，seller 端用于校验资源一致性。
+ *
+ * @param slug 资源 slug
+ * @returns 小写十六进制的 MD5 摘要
  */
 export function computeIndicator(slug: string): string {
   return crypto.createHash("md5").update(slug, "utf8").digest("hex");
 }
 
 /**
- * Generate a 32-character lowercase hex string as orderNo (UUID v4 without dashes).
+ * 生成 32 字符小写十六进制字符串作为订单号。
+ * 实现细节：UUID v4 去除中横线，保证全局唯一且 URL/日志友好。
+ *
+ * @returns 32 字符小写 hex 字符串
  */
 export function generateOrderNo(): string {
   return uuidv4().replace(/-/g, "");
 }
 
 /**
- * Encrypt Clawtip order data: {"orderNo":..., "amount":..., "payTo":...}
- * Returns the base64 encrypted data.
+ * 加密 Clawtip 订单数据。
+ * 明文格式：`{"orderNo":..., "amount":..., "payTo":...}`，使用 SM4-ECB-PKCS7 加密后 base64 编码。
+ *
+ * @param orderNo 订单号
+ * @param amount 订单金额（分）
+ * @param payTo 收款方标识
+ * @param sm4KeyBase64 SM4 密钥的 base64 编码（必须解码为 16 字节）
+ * @returns base64 编码的密文
  */
 export function encryptClawtipOrderData(
   orderNo: string,
@@ -78,28 +91,61 @@ export function encryptClawtipOrderData(
   return encryptSm4EcbPkcs7Base64(plaintext, sm4KeyBase64);
 }
 
+/**
+ * Clawtip 支付下单所需的完整参数。
+ * 由 `buildClawtipPaymentParams` 在 buyer 端组装后下发到 seller。
+ */
 export interface ClawtipPaymentParams {
+  /** 32 字符小写十六进制的订单号（UUID v4 去横线），全局唯一标识一次下单 */
   orderNo: string;
+  /** 订单金额，单位为分（人民币 1 元 = 100 分） */
   amountFen: number;
+  /** 收款方标识，seller 校验该字段决定打款目标 */
   payTo: string;
+  /** SM4-ECB-PKCS7 加密的 `{orderNo, amount, payTo}` JSON，base64 编码 */
   encryptedData: string;
+  /** 资源 slug 的 MD5 摘要，用于 seller 校验资源一致性 */
   indicator: string;
+  /** 资源 slug（人类可读 ID），与 indicator 配对使用 */
   slug: string;
+  /** Clawtip 平台的技能 ID */
   skillId: string;
+  /** 支付场景的人类可读描述，展示给支付方 */
   description: string;
+  /** 资源下载/访问 URL，可用于支付完成后的资源定位 */
   resourceUrl: string;
 }
 
+/**
+ * 构造 `ClawtipPaymentParams` 所需的原始输入。
+ * 调用方只需要提供业务字段；`orderNo` 和 `encryptedData` 由 builder 自动生成。
+ */
 export interface ClawtipPaymentParamsInput {
+  /** 收款方标识 */
   payTo: string;
+  /** SM4 密钥的 base64 编码（解密后必须为 16 字节） */
   sm4KeyBase64: string;
+  /** 资源 slug，会同时参与 indicator 计算 */
   skillSlug: string;
+  /** Clawtip 平台的技能 ID */
   skillId: string;
+  /** 支付场景描述 */
   description: string;
+  /** 资源 URL */
   resourceUrl: string;
+  /** 订单金额（分），必须为正整数 */
   amountFen: number;
 }
 
+/**
+ * 构造 `ClawtipPaymentParams` 完整参数。
+ * 负责：生成 `orderNo`、对 `(orderNo, amount, payTo)` 做 SM4 加密、计算 `indicator`。
+ * `amountFen` 必须为正整数，否则抛错。
+ *
+ * @param input 业务字段输入
+ * @returns 包含加密数据的完整支付参数
+ * @throws Error 当 `amountFen` 不是正整数时
+ */
 export function buildClawtipPaymentParams(input: ClawtipPaymentParamsInput): ClawtipPaymentParams {
   if (!Number.isInteger(input.amountFen) || input.amountFen < 1) {
     throw new Error("amount_fen must be greater than zero");

package/src/errors.ts

@@ -32,6 +32,13 @@ export enum ErrorCode {
   ContractVersionDrift = "contract_version_drift"
 }
 
+/**
+ * 错误码到重试策略分类的映射。
+ * buyer / seller 路由层根据该结果决定是否自动重试、是否触发 fail-closed。
+ *
+ * @param code 业务错误码
+ * @returns 重试分类：`RetryableWithBackoff`（建议退避重试）、`FailClosed`（关闭交易、人工介入）、`NotRetryable`（直接报错给用户）
+ */
 export function getRetryClass(code: ErrorCode): RetryClass {
   switch (code) {
     case ErrorCode.BusyCapacity:
@@ -46,6 +53,13 @@ export function getRetryClass(code: ErrorCode): RetryClass {
   }
 }
 
+/**
+ * 错误码到 HTTP 状态码的映射。
+ * 当协议层把业务错误透传为 HTTP 响应（如 buyer → wallet-bootstrap 健康检查）时使用。
+ *
+ * @param code 业务错误码
+ * @returns 对应的 HTTP 状态码（4xx/5xx）
+ */
 export function getHttpStatus(code: ErrorCode): number {
   switch (code) {
     case ErrorCode.BusyCapacity:
@@ -87,6 +101,13 @@ export function getHttpStatus(code: ErrorCode): number {
   }
 }
 
+/**
+ * 错误码到默认人类可读消息的映射。
+ * 用于 `createErrorEnvelope` 未传 `message` 参数时的兜底文案。
+ *
+ * @param code 业务错误码
+ * @returns 默认错误消息
+ */
 export function getDefaultMessage(code: ErrorCode): string {
   switch (code) {
     case ErrorCode.BusyCapacity:
@@ -144,18 +165,39 @@ export function getDefaultMessage(code: ErrorCode): string {
   }
 }
 
+/**
+ * 标准错误体的字段定义。HTTP 响应或 JSON-RPC error 对象均使用该结构。
+ */
 export interface ErrorBody {
+  /** 机器可读的错误码，用于客户端做错误分支处理 */
   code: ErrorCode;
+  /** 错误重试分类（fail_closed / retryable_with_backoff / not_retryable） */
   retryClass: RetryClass;
+  /** 人类可读的错误描述 */
   message: string;
+  /** 推荐的 HTTP 状态码，HTTP 透传场景下使用 */
   httpStatus: number;
+  /** 退避建议秒数（仅 429/重试类错误附带） */
   retryAfterSeconds?: number;
 }
 
+/**
+ * 错误响应的标准外壳。所有非 2xx 响应都以 `{ error: {...} }` 形式返回。
+ */
 export interface ErrorEnvelope {
+  /** 嵌套的错误体 */
   error: ErrorBody;
 }
 
+/**
+ * 构造标准错误响应外壳。
+ * 自动填充 `retryClass`、`httpStatus`、默认 `message`，调用方只需提供 `code` 和可选的覆盖字段。
+ *
+ * @param code 业务错误码，决定 retryClass / httpStatus / 默认 message
+ * @param message 自定义消息；省略时使用 `getDefaultMessage(code)` 兜底文案
+ * @param retryAfterSeconds 退避秒数，仅在需要时填入（如 429）
+ * @returns 完整的 `ErrorEnvelope` 对象
+ */
 export function createErrorEnvelope(
   code: ErrorCode,
   message?: string,

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from "./errors.js";
 export * from "./crypto.js";
+export * from "./upstream-balance-probe.js";