@tokenbuddy/contracts 1.0.0 → 1.0.37

package/dist/src/crypto.d.ts

@@ -9,37 +9,83 @@ export declare function encryptSm4EcbPkcs7Base64(plaintext: string, sm4KeyBase64
  */
 export declare function decryptSm4EcbPkcs7Base64(encryptedBase64: string, sm4KeyBase64: string): string;
 /**
- * Compute md5 hex digest of a string (indicator).
+ * 计算资源 slug 的 MD5 摘要（hex 编码）。
+ * 用作 Clawtip 支付的 indicator 字段，seller 端用于校验资源一致性。
+ *
+ * @param slug 资源 slug
+ * @returns 小写十六进制的 MD5 摘要
  */
 export declare function computeIndicator(slug: string): string;
 /**
- * Generate a 32-character lowercase hex string as orderNo (UUID v4 without dashes).
+ * 生成 32 字符小写十六进制字符串作为订单号。
+ * 实现细节：UUID v4 去除中横线，保证全局唯一且 URL/日志友好。
+ *
+ * @returns 32 字符小写 hex 字符串
  */
 export declare function generateOrderNo(): string;
 /**
- * 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 declare function encryptClawtipOrderData(orderNo: string, amount: number, payTo: string, sm4KeyBase64: string): string;
+/**
+ * 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 declare function buildClawtipPaymentParams(input: ClawtipPaymentParamsInput): ClawtipPaymentParams;
 //# sourceMappingURL=crypto.d.ts.map

package/dist/src/crypto.js

@@ -86,20 +86,33 @@ function decryptSm4EcbPkcs7Base64(encryptedBase64, sm4KeyBase64) {
     }
 }
 /**
- * Compute md5 hex digest of a string (indicator).
+ * 计算资源 slug 的 MD5 摘要（hex 编码）。
+ * 用作 Clawtip 支付的 indicator 字段，seller 端用于校验资源一致性。
+ *
+ * @param slug 资源 slug
+ * @returns 小写十六进制的 MD5 摘要
  */
 function computeIndicator(slug) {
     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 字符串
  */
 function generateOrderNo() {
     return (0, uuid_1.v4)().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 编码的密文
  */
 function encryptClawtipOrderData(orderNo, amount, payTo, sm4KeyBase64) {
     const plaintext = JSON.stringify({
@@ -109,6 +122,15 @@ function encryptClawtipOrderData(orderNo, amount, payTo, sm4KeyBase64) {
     });
     return encryptSm4EcbPkcs7Base64(plaintext, sm4KeyBase64);
 }
+/**
+ * 构造 `ClawtipPaymentParams` 完整参数。
+ * 负责：生成 `orderNo`、对 `(orderNo, amount, payTo)` 做 SM4 加密、计算 `indicator`。
+ * `amountFen` 必须为正整数，否则抛错。
+ *
+ * @param input 业务字段输入
+ * @returns 包含加密数据的完整支付参数
+ * @throws Error 当 `amountFen` 不是正整数时
+ */
 function buildClawtipPaymentParams(input) {
     if (!Number.isInteger(input.amountFen) || input.amountFen < 1) {
         throw new Error("amount_fen must be greater than zero");

package/dist/src/errors.d.ts

@@ -30,18 +30,60 @@ export declare enum ErrorCode {
     UpstreamTimeout = "upstream_timeout",
     ContractVersionDrift = "contract_version_drift"
 }
+/**
+ * 错误码到重试策略分类的映射。
+ * buyer / seller 路由层根据该结果决定是否自动重试、是否触发 fail-closed。
+ *
+ * @param code 业务错误码
+ * @returns 重试分类：`RetryableWithBackoff`（建议退避重试）、`FailClosed`（关闭交易、人工介入）、`NotRetryable`（直接报错给用户）
+ */
 export declare function getRetryClass(code: ErrorCode): RetryClass;
+/**
+ * 错误码到 HTTP 状态码的映射。
+ * 当协议层把业务错误透传为 HTTP 响应（如 buyer → wallet-bootstrap 健康检查）时使用。
+ *
+ * @param code 业务错误码
+ * @returns 对应的 HTTP 状态码（4xx/5xx）
+ */
 export declare function getHttpStatus(code: ErrorCode): number;
+/**
+ * 错误码到默认人类可读消息的映射。
+ * 用于 `createErrorEnvelope` 未传 `message` 参数时的兜底文案。
+ *
+ * @param code 业务错误码
+ * @returns 默认错误消息
+ */
 export declare 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 declare function createErrorEnvelope(code: ErrorCode, message?: string, retryAfterSeconds?: number): ErrorEnvelope;
 //# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.js

@@ -39,6 +39,13 @@ var ErrorCode;
     ErrorCode["UpstreamTimeout"] = "upstream_timeout";
     ErrorCode["ContractVersionDrift"] = "contract_version_drift";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+/**
+ * 错误码到重试策略分类的映射。
+ * buyer / seller 路由层根据该结果决定是否自动重试、是否触发 fail-closed。
+ *
+ * @param code 业务错误码
+ * @returns 重试分类：`RetryableWithBackoff`（建议退避重试）、`FailClosed`（关闭交易、人工介入）、`NotRetryable`（直接报错给用户）
+ */
 function getRetryClass(code) {
     switch (code) {
         case ErrorCode.BusyCapacity:
@@ -52,6 +59,13 @@ function getRetryClass(code) {
             return RetryClass.NotRetryable;
     }
 }
+/**
+ * 错误码到 HTTP 状态码的映射。
+ * 当协议层把业务错误透传为 HTTP 响应（如 buyer → wallet-bootstrap 健康检查）时使用。
+ *
+ * @param code 业务错误码
+ * @returns 对应的 HTTP 状态码（4xx/5xx）
+ */
 function getHttpStatus(code) {
     switch (code) {
         case ErrorCode.BusyCapacity:
@@ -92,6 +106,13 @@ function getHttpStatus(code) {
             return 500;
     }
 }
+/**
+ * 错误码到默认人类可读消息的映射。
+ * 用于 `createErrorEnvelope` 未传 `message` 参数时的兜底文案。
+ *
+ * @param code 业务错误码
+ * @returns 默认错误消息
+ */
 function getDefaultMessage(code) {
     switch (code) {
         case ErrorCode.BusyCapacity:
@@ -148,6 +169,15 @@ function getDefaultMessage(code) {
             return "An unknown error occurred.";
     }
 }
+/**
+ * 构造标准错误响应外壳。
+ * 自动填充 `retryClass`、`httpStatus`、默认 `message`，调用方只需提供 `code` 和可选的覆盖字段。
+ *
+ * @param code 业务错误码，决定 retryClass / httpStatus / 默认 message
+ * @param message 自定义消息；省略时使用 `getDefaultMessage(code)` 兜底文案
+ * @param retryAfterSeconds 退避秒数，仅在需要时填入（如 429）
+ * @returns 完整的 `ErrorEnvelope` 对象
+ */
 function createErrorEnvelope(code, message, retryAfterSeconds) {
     return {
         error: {

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./errors.js";
 export * from "./crypto.js";
+export * from "./upstream-balance-probe.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./errors.js"), exports);
 __exportStar(require("./crypto.js"), exports);
+__exportStar(require("./upstream-balance-probe.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/src/upstream-balance-probe.d.ts

@@ -0,0 +1,41 @@
+export type BalanceCurrency = "USD" | "CNY" | null;
+export type BalanceSource = "deepseek" | "stepfun" | "siliconflow" | "openrouter" | "novita" | "newapi_generic" | "usage_generic" | "unknown";
+export type BalanceProbeTemplate = "auto" | "deepseek" | "stepfun" | "siliconflow" | "openrouter" | "novita" | "newapi_generic" | "usage_generic" | "none";
+export interface BalanceSnapshot {
+    rawAmount: number | null;
+    amountUsdMicros: number | null;
+    currency: BalanceCurrency;
+    source: BalanceSource;
+    fetchedAt: number;
+    error?: {
+        httpStatus: number;
+        message: string;
+    };
+}
+export interface BalanceProbeConfig {
+    upstreamUrl?: string;
+    upstreamBalanceUrl?: string;
+    upstreamApiKey?: string;
+    upstreamUserId?: string;
+    upstreamBalanceProbe?: {
+        template?: BalanceProbeTemplate;
+        url?: string;
+        userId?: string;
+        rechargeUrl?: string;
+    };
+}
+export interface BalanceProbeOptions {
+    fetch?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+    cnyUsdRate?: number;
+    cache?: BalanceProbeCache;
+}
+export declare class BalanceProbeCache {
+    private readonly entries;
+    get(key: string, now: number): BalanceSnapshot | undefined;
+    setFailure(key: string, snapshot: BalanceSnapshot, now: number): void;
+}
+export declare const defaultBalanceProbeCache: BalanceProbeCache;
+export declare function probeUpstreamBalance(config: BalanceProbeConfig, options?: BalanceProbeOptions): Promise<BalanceSnapshot>;
+//# sourceMappingURL=upstream-balance-probe.d.ts.map

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/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@tokenbuddy/contracts",
-  "version": "1.0.0",
+  "version": "1.0.37",
   "description": "Shared contract models and crypto functions",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "private": false,
+  "files": [
+    "dist/src/**/*.js",
+    "dist/src/**/*.d.ts"
+  ],
   "scripts": {
     "build": "tsc"
   },
@@ -14,4 +18,4 @@
   "devDependencies": {
     "@types/uuid": "^9.0.8"
   }
-}
+}

package/dist/src/crypto.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/crypto.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAWxF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAU9F;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,MAAM,CAOR;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,yBAAyB,GAAG,oBAAoB,CAiBhG"}

package/dist/src/crypto.js.map

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

package/dist/src/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,oBAAY,UAAU;IACpB,UAAU,gBAAgB;IAC1B,oBAAoB,2BAA2B;IAC/C,YAAY,kBAAkB;CAC/B;AAED,oBAAY,SAAS;IACnB,YAAY,kBAAkB;IAC9B,eAAe,qBAAqB;IACpC,0BAA0B,iCAAiC;IAC3D,qBAAqB,6BAA6B;IAClD,4BAA4B,mCAAmC;IAC/D,gBAAgB,sBAAsB;IACtC,cAAc,oBAAoB;IAClC,qBAAqB,4BAA4B;IACjD,sBAAsB,6BAA6B;IACnD,wBAAwB,+BAA+B;IACvD,oBAAoB,2BAA2B;IAC/C,iBAAiB,uBAAuB;IACxC,qBAAqB,6BAA6B;IAClD,iBAAiB,wBAAwB;IACzC,iBAAiB,wBAAwB;IACzC,qBAAqB,4BAA4B;IACjD,mBAAmB,yBAAyB;IAC5C,gBAAgB,uBAAuB;IACvC,eAAe,sBAAsB;IACrC,iBAAiB,wBAAwB;IACzC,qBAAqB,4BAA4B;IACjD,oBAAoB,2BAA2B;IAC/C,gBAAgB,uBAAuB;IACvC,eAAe,qBAAqB;IACpC,oBAAoB,2BAA2B;CAChD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAYzD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAuCrD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAuDzD;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,EACf,OAAO,CAAC,EAAE,MAAM,EAChB,iBAAiB,CAAC,EAAE,MAAM,GACzB,aAAa,CAUf"}

package/dist/src/errors.js.map

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

package/dist/src/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/src/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,8CAA4B"}

package/src/crypto.ts

@@ -1,120 +0,0 @@
-import * as crypto from "crypto";
-import { v4 as uuidv4 } from "uuid";
-
-/**
- * Decode a base64 SM4 key to a 16-byte Buffer.
- * Throws an error if the decoded key is not exactly 16 bytes.
- */
-function decodeSm4Key(sm4KeyBase64: string): Buffer {
-  const key = Buffer.from(sm4KeyBase64, "base64");
-  if (key.length !== 16) {
-    throw new Error(`SM4 key must decode to 16 bytes, got ${key.length}`);
-  }
-  return key;
-}
-
-/**
- * Encrypt a plaintext string using SM4-ECB with PKCS7 padding.
- * Returns the ciphertext encoded as a base64 string.
- */
-export function encryptSm4EcbPkcs7Base64(plaintext: string, sm4KeyBase64: string): string {
-  try {
-    const key = decodeSm4Key(sm4KeyBase64);
-    // Node.js crypto uses 'sm4-ecb' which defaults to PKCS7 padding for ECB
-    const cipher = crypto.createCipheriv("sm4-ecb", key, null);
-    let encrypted = cipher.update(plaintext, "utf8", "base64");
-    encrypted += cipher.final("base64");
-    return encrypted;
-  } catch (error: any) {
-    throw new Error(`SM4 encryption failed: ${error.message}`);
-  }
-}
-
-/**
- * Decrypt a base64 ciphertext string using SM4-ECB with PKCS7 padding.
- * Returns the decrypted plaintext string.
- */
-export function decryptSm4EcbPkcs7Base64(encryptedBase64: string, sm4KeyBase64: string): string {
-  try {
-    const key = decodeSm4Key(sm4KeyBase64);
-    const decipher = crypto.createDecipheriv("sm4-ecb", key, null);
-    let decrypted = decipher.update(encryptedBase64, "base64", "utf8");
-    decrypted += decipher.final("utf8");
-    return decrypted;
-  } catch (error: any) {
-    throw new Error(`SM4 decryption failed: ${error.message}`);
-  }
-}
-
-/**
- * Compute md5 hex digest of a string (indicator).
- */
-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).
- */
-export function generateOrderNo(): string {
-  return uuidv4().replace(/-/g, "");
-}
-
-/**
- * Encrypt Clawtip order data: {"orderNo":..., "amount":..., "payTo":...}
- * Returns the base64 encrypted data.
- */
-export function encryptClawtipOrderData(
-  orderNo: string,
-  amount: number,
-  payTo: string,
-  sm4KeyBase64: string
-): string {
-  const plaintext = JSON.stringify({
-    orderNo,
-    amount,
-    payTo
-  });
-  return encryptSm4EcbPkcs7Base64(plaintext, sm4KeyBase64);
-}
-
-export interface ClawtipPaymentParams {
-  orderNo: string;
-  amountFen: number;
-  payTo: string;
-  encryptedData: string;
-  indicator: string;
-  slug: string;
-  skillId: string;
-  description: string;
-  resourceUrl: string;
-}
-
-export interface ClawtipPaymentParamsInput {
-  payTo: string;
-  sm4KeyBase64: string;
-  skillSlug: string;
-  skillId: string;
-  description: string;
-  resourceUrl: string;
-  amountFen: number;
-}
-
-export function buildClawtipPaymentParams(input: ClawtipPaymentParamsInput): ClawtipPaymentParams {
-  if (!Number.isInteger(input.amountFen) || input.amountFen < 1) {
-    throw new Error("amount_fen must be greater than zero");
-  }
-
-  const orderNo = generateOrderNo();
-  return {
-    orderNo,
-    amountFen: input.amountFen,
-    payTo: input.payTo,
-    encryptedData: encryptClawtipOrderData(orderNo, input.amountFen, input.payTo, input.sm4KeyBase64),
-    indicator: computeIndicator(input.skillSlug),
-    slug: input.skillSlug,
-    skillId: input.skillId,
-    description: input.description,
-    resourceUrl: input.resourceUrl
-  };
-}

package/src/errors.ts

@@ -1,173 +0,0 @@
-export enum RetryClass {
-  FailClosed = "fail_closed",
-  RetryableWithBackoff = "retryable_with_backoff",
-  NotRetryable = "not_retryable"
-}
-
-export enum ErrorCode {
-  BusyCapacity = "busy_capacity",
-  PaymentRequired = "payment_required",
-  PaymentAccountInsufficient = "payment_account_insufficient",
-  PaymentMethodNotReady = "payment_method_not_ready",
-  PaymentAuthorizationRequired = "payment_authorization_required",
-  PaymentCancelled = "payment_cancelled",
-  PaymentTimeout = "payment_timeout",
-  PaymentProviderFailed = "payment_provider_failed",
-  InvalidPurchaseRequest = "invalid_purchase_request",
-  ClawtipCredentialInvalid = "clawtip_credential_invalid",
-  ClawtipOrderMismatch = "clawtip_order_mismatch",
-  InsufficientFunds = "insufficient_funds",
-  InvalidOrExpiredToken = "invalid_or_expired_token",
-  TokenClassRevoked = "token_class_revoked",
-  RequestIdRequired = "request_id_required",
-  StreamingNotSupported = "streaming_not_supported",
-  IdempotencyConflict = "idempotency_conflict",
-  PurchaseNotFound = "purchase_not_found",
-  RequestNotFound = "request_not_found",
-  ModelNotAvailable = "model_not_available",
-  UpstreamNotConfigured = "upstream_not_configured",
-  ProtocolNotAvailable = "protocol_not_available",
-  LedgerFailClosed = "ledger_fail_closed",
-  UpstreamTimeout = "upstream_timeout",
-  ContractVersionDrift = "contract_version_drift"
-}
-
-export function getRetryClass(code: ErrorCode): RetryClass {
-  switch (code) {
-    case ErrorCode.BusyCapacity:
-    case ErrorCode.UpstreamTimeout:
-      return RetryClass.RetryableWithBackoff;
-    case ErrorCode.LedgerFailClosed:
-    case ErrorCode.ClawtipCredentialInvalid:
-    case ErrorCode.ClawtipOrderMismatch:
-      return RetryClass.FailClosed;
-    default:
-      return RetryClass.NotRetryable;
-  }
-}
-
-export function getHttpStatus(code: ErrorCode): number {
-  switch (code) {
-    case ErrorCode.BusyCapacity:
-      return 429;
-    case ErrorCode.PaymentRequired:
-    case ErrorCode.PaymentAccountInsufficient:
-    case ErrorCode.PaymentMethodNotReady:
-    case ErrorCode.PaymentAuthorizationRequired:
-    case ErrorCode.PaymentCancelled:
-    case ErrorCode.PaymentTimeout:
-    case ErrorCode.PaymentProviderFailed:
-    case ErrorCode.ClawtipCredentialInvalid:
-    case ErrorCode.ClawtipOrderMismatch:
-    case ErrorCode.InsufficientFunds:
-      return 402;
-    case ErrorCode.InvalidPurchaseRequest:
-      return 400;
-    case ErrorCode.InvalidOrExpiredToken:
-    case ErrorCode.TokenClassRevoked:
-      return 401;
-    case ErrorCode.RequestIdRequired:
-    case ErrorCode.StreamingNotSupported:
-    case ErrorCode.ModelNotAvailable:
-    case ErrorCode.UpstreamNotConfigured:
-    case ErrorCode.ProtocolNotAvailable:
-    case ErrorCode.ContractVersionDrift:
-      return 400;
-    case ErrorCode.IdempotencyConflict:
-      return 409;
-    case ErrorCode.PurchaseNotFound:
-    case ErrorCode.RequestNotFound:
-      return 404;
-    case ErrorCode.LedgerFailClosed:
-      return 500;
-    case ErrorCode.UpstreamTimeout:
-      return 504;
-    default:
-      return 500;
-  }
-}
-
-export function getDefaultMessage(code: ErrorCode): string {
-  switch (code) {
-    case ErrorCode.BusyCapacity:
-      return "Seller capacity is currently exhausted.";
-    case ErrorCode.PaymentRequired:
-      return "Additional credit is required before this operation can proceed.";
-    case ErrorCode.PaymentAccountInsufficient:
-      return "Payment account balance is insufficient. Add funds to the selected payment method and retry.";
-    case ErrorCode.PaymentMethodNotReady:
-      return "Selected payment method is not ready. Configure or enable a payment method and retry.";
-    case ErrorCode.PaymentAuthorizationRequired:
-      return "Selected payment method requires authorization before payment can proceed.";
-    case ErrorCode.PaymentCancelled:
-      return "Payment was cancelled before completion.";
-    case ErrorCode.PaymentTimeout:
-      return "Payment did not complete before the timeout.";
-    case ErrorCode.PaymentProviderFailed:
-      return "Selected payment provider could not complete the payment.";
-    case ErrorCode.ClawtipCredentialInvalid:
-      return "Clawtip payment credential is invalid.";
-    case ErrorCode.InvalidPurchaseRequest:
-      return "Purchase request is invalid.";
-    case ErrorCode.ClawtipOrderMismatch:
-      return "Clawtip payment does not match the expected order.";
-    case ErrorCode.InsufficientFunds:
-      return "Purchase balance is exhausted.";
-    case ErrorCode.InvalidOrExpiredToken:
-      return "Bearer token is invalid or expired.";
-    case ErrorCode.TokenClassRevoked:
-      return "Token class has been revoked by seller operator.";
-    case ErrorCode.RequestIdRequired:
-      return "Chat requests must include requestId.";
-    case ErrorCode.StreamingNotSupported:
-      return "Streaming responses are not supported in P0.";
-    case ErrorCode.IdempotencyConflict:
-      return "Idempotency key was reused with a different request payload.";
-    case ErrorCode.PurchaseNotFound:
-      return "Purchase could not be found.";
-    case ErrorCode.RequestNotFound:
-      return "Request could not be found.";
-    case ErrorCode.ModelNotAvailable:
-      return "Requested model is not available on this seller.";
-    case ErrorCode.UpstreamNotConfigured:
-      return "Seller upstream is not configured. Ask the seller operator to configure upstreams.";
-    case ErrorCode.ProtocolNotAvailable:
-      return "Requested protocol is not available for this seller upstream.";
-    case ErrorCode.LedgerFailClosed:
-      return "Ledger entered fail-closed mode.";
-    case ErrorCode.UpstreamTimeout:
-      return "Upstream model request timed out.";
-    case ErrorCode.ContractVersionDrift:
-      return "Contract version drift detected.";
-    default:
-      return "An unknown error occurred.";
-  }
-}
-
-export interface ErrorBody {
-  code: ErrorCode;
-  retryClass: RetryClass;
-  message: string;
-  httpStatus: number;
-  retryAfterSeconds?: number;
-}
-
-export interface ErrorEnvelope {
-  error: ErrorBody;
-}
-
-export function createErrorEnvelope(
-  code: ErrorCode,
-  message?: string,
-  retryAfterSeconds?: number
-): ErrorEnvelope {
-  return {
-    error: {
-      code,
-      retryClass: getRetryClass(code),
-      message: message || getDefaultMessage(code),
-      httpStatus: getHttpStatus(code),
-      ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {})
-    }
-  };
-}

package/src/index.ts

@@ -1,2 +0,0 @@
-export * from "./errors.js";
-export * from "./crypto.js";

package/tests/crypto.test.ts

@@ -1,91 +0,0 @@
-import {
-  encryptSm4EcbPkcs7Base64,
-  decryptSm4EcbPkcs7Base64,
-  computeIndicator,
-  generateOrderNo,
-  encryptClawtipOrderData,
-  buildClawtipPaymentParams
-} from "../src/crypto.js";
-
-// base64("0123456789ABCDEF") — exactly 16 bytes
-const KEY = "MDEyMzQ1Njc4OUFCQ0RFRg==";
-
-describe("SM4 Cryptography and Helpers Tests", () => {
-  test("sm4 ecb pkcs7 roundtrip", () => {
-    const plaintext = '{"orderNo":"abc123","amount":100,"payTo":"payto-test"}';
-    const encrypted = encryptSm4EcbPkcs7Base64(plaintext, KEY);
-    const decrypted = decryptSm4EcbPkcs7Base64(encrypted, KEY);
-    
-    expect(encrypted).not.toBe(plaintext);
-    expect(decrypted).toBe(plaintext);
-  });
-
-  test("sm4 invalid base64 key throws error", () => {
-    expect(() => {
-      encryptSm4EcbPkcs7Base64("hello", "!!!not-base64!!!");
-    }).toThrow();
-  });
-
-  test("sm4 short key throws error", () => {
-    // base64("short") = 8 bytes
-    expect(() => {
-      encryptSm4EcbPkcs7Base64("hello", "c2hvcnQ=");
-    }).toThrow("16 bytes");
-  });
-
-  test("compute_indicator is md5 hex of slug", () => {
-    // echo -n "test" | md5sum => 098f6bcd4621d373cade4e832627b4f6
-    expect(computeIndicator("test")).toBe("098f6bcd4621d373cade4e832627b4f6");
-  });
-
-  test("generate_order_no is 32 lowercase hex chars", () => {
-    const no = generateOrderNo();
-    expect(no.length).toBe(32);
-    expect(/^[0-9a-f]{32}$/.test(no)).toBe(true);
-  });
-
-  test("encryptClawtipOrderData produces valid json after decrypt", () => {
-    const enc = encryptClawtipOrderData("ord001", 500, "pay-to-addr", KEY);
-    const dec = decryptSm4EcbPkcs7Base64(enc, KEY);
-    const val = JSON.parse(dec);
-    expect(val.orderNo).toBe("ord001");
-    expect(val.amount).toBe(500);
-    expect(val.payTo).toBe("pay-to-addr");
-  });
-
-  test("buildClawtipPaymentParams produces the shared wallet bootstrap shape", () => {
-    const params = buildClawtipPaymentParams({
-      payTo: "pay-to-addr",
-      sm4KeyBase64: KEY,
-      skillSlug: "tb-wallet-bootstrap",
-      skillId: "si-tb-wallet-bootstrap",
-      description: "Activate",
-      resourceUrl: "https://example.com",
-      amountFen: 1
-    });
-
-    expect(params.amountFen).toBe(1);
-    expect(params.payTo).toBe("pay-to-addr");
-    expect(params.slug).toBe("tb-wallet-bootstrap");
-    expect(params.skillId).toBe("si-tb-wallet-bootstrap");
-    expect(params.orderNo).toMatch(/^[0-9a-f]{32}$/);
-    expect(params.indicator).toBe(computeIndicator("tb-wallet-bootstrap"));
-
-    const decoded = JSON.parse(decryptSm4EcbPkcs7Base64(params.encryptedData, KEY));
-    expect(decoded.orderNo).toBe(params.orderNo);
-    expect(decoded.amount).toBe(1);
-    expect(decoded.payTo).toBe("pay-to-addr");
-  });
-
-  test("buildClawtipPaymentParams rejects non-positive amountFen", () => {
-    expect(() => buildClawtipPaymentParams({
-      payTo: "pay-to-addr",
-      sm4KeyBase64: KEY,
-      skillSlug: "tb-wallet-bootstrap",
-      skillId: "si-tb-wallet-bootstrap",
-      description: "Activate",
-      resourceUrl: "https://example.com",
-      amountFen: 0
-    })).toThrow("amount_fen");
-  });
-});

package/tests/errors.test.ts

@@ -1,34 +0,0 @@
-import {
-  ErrorCode,
-  RetryClass,
-  getRetryClass,
-  getHttpStatus,
-  getDefaultMessage,
-  createErrorEnvelope
-} from "../src/errors.js";
-
-describe("ErrorCode and RetryClass Mapping Tests", () => {
-  test("retry class maps correctly", () => {
-    expect(getRetryClass(ErrorCode.BusyCapacity)).toBe(RetryClass.RetryableWithBackoff);
-    expect(getRetryClass(ErrorCode.UpstreamTimeout)).toBe(RetryClass.RetryableWithBackoff);
-    expect(getRetryClass(ErrorCode.LedgerFailClosed)).toBe(RetryClass.FailClosed);
-    expect(getRetryClass(ErrorCode.ClawtipCredentialInvalid)).toBe(RetryClass.FailClosed);
-    expect(getRetryClass(ErrorCode.PaymentRequired)).toBe(RetryClass.NotRetryable);
-  });
-
-  test("http status maps correctly", () => {
-    expect(getHttpStatus(ErrorCode.BusyCapacity)).toBe(429);
-    expect(getHttpStatus(ErrorCode.PaymentRequired)).toBe(402);
-    expect(getHttpStatus(ErrorCode.InvalidOrExpiredToken)).toBe(401);
-    expect(getHttpStatus(ErrorCode.LedgerFailClosed)).toBe(500);
-    expect(getHttpStatus(ErrorCode.UpstreamTimeout)).toBe(504);
-  });
-
-  test("createErrorEnvelope produces standard wire structure", () => {
-    const envelope = createErrorEnvelope(ErrorCode.BusyCapacity);
-    expect(envelope.error.code).toBe(ErrorCode.BusyCapacity);
-    expect(envelope.error.retryClass).toBe(RetryClass.RetryableWithBackoff);
-    expect(envelope.error.httpStatus).toBe(429);
-    expect(envelope.error.message).toContain("capacity");
-  });
-});

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./"
-  },
-  "include": ["src/**/*"]
-}