@xiashe/sdk 0.1.11 → 0.1.13

package/alipayWallet.mjs

@@ -1,9 +1,15 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
 
 const DEFAULT_TIMEOUT_MS = 8 * 60 * 1000;
+const RESOURCE_FETCH_TIMEOUT_MS = 20 * 1000;
 const MAX_OUTPUT_BYTES = 32 * 1024;
 const SENSITIVE_OUTPUT = /payment[-_ ]?proof|payment[-_ ]?needed|seller_signature|runtimeToken|authorization\s*:/i;
+const SENSITIVE_USER_OUTPUT = /payment[-_ ]?proof|payment[-_ ]?needed|seller_signature|runtimeToken|authorization\s*:|trade[_ -]?no|交易(?:流水)?号|out[_ -]?shake|client[_ -]?session/i;
+const DEFAULT_STATE_DIR = path.join(os.homedir(), '.xiashe', 'alipay-402');
 
 export class AlipayWalletError extends Error {
   constructor(code, message, options = {}) {
@@ -19,14 +25,14 @@ function safeText(value, maxLength = 240) {
 }
 
 function digest(value) {
-  return createHash('sha256').update(String(value || '')).digest('hex').slice(0, 16);
+  return createHash('sha256').update(String(value || '')).digest('hex');
 }
 
 function safeDiagnostic(value) {
   const text = safeText(value, MAX_OUTPUT_BYTES);
   if (!text) return 'no_wallet_output';
-  // CLI output is not a protocol API: never forward it to an Agent. This
-  // protects future vendor versions even when they add fields we do not know.
+  // Vendor output is not a stable public API. Never forward it because a new
+  // version could include a protocol proof or another credential.
   return SENSITIVE_OUTPUT.test(text) ? 'protocol_payload_processed' : 'official_wallet_response_received';
 }
 
@@ -51,6 +57,48 @@ function normalizeIntentSummary(value) {
   return summary;
 }
 
+function stateDirectory(options = {}) {
+  return path.resolve(options.stateDir || process.env.XIASHE_ALIPAY_PAYMENT_STATE_DIR || DEFAULT_STATE_DIR);
+}
+
+function statePaths(resourceUrl, options = {}) {
+  const base = digest(resourceUrl);
+  const directory = stateDirectory(options);
+  return {
+    directory,
+    paymentNeededPath: path.join(directory, `${base}.txt`),
+    statePath: path.join(directory, `${base}.json`)
+  };
+}
+
+async function ensurePrivateDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  // mkdir does not change permissions of an existing directory.
+  await chmod(directory, 0o700);
+}
+
+async function writePrivateFile(filePath, contents) {
+  await writeFile(filePath, contents, { encoding: 'utf8', mode: 0o600 });
+  await chmod(filePath, 0o600);
+}
+
+async function readPaymentState(resourceUrl, options = {}) {
+  const { statePath } = statePaths(resourceUrl, options);
+  try {
+    const parsed = JSON.parse(await readFile(statePath, 'utf8'));
+    return parsed && parsed.version === 1 && parsed.resourceDigest === digest(resourceUrl) ? parsed : null;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw new AlipayWalletError('ALIPAY_PAYMENT_STATE_INVALID', '本地支付宝付款状态无法读取；请重新发起本次付款。');
+  }
+}
+
+async function writePaymentState(state, options = {}) {
+  const { directory, statePath } = statePaths(state.resourceUrl, options);
+  await ensurePrivateDirectory(directory);
+  await writePrivateFile(statePath, `${JSON.stringify(state)}\n`);
+}
+
 function defaultRunFile(command, args, options) {
   return new Promise((resolve, reject) => {
     execFile(command, args, {
@@ -71,8 +119,12 @@ function defaultRunFile(command, args, options) {
 }
 
 function normalizedRunnerResult(result) {
-  if (typeof result === 'string') return { stdout: result, stderr: '' };
-  return { stdout: String(result?.stdout || ''), stderr: String(result?.stderr || '') };
+  if (typeof result === 'string') return { stdout: result, stderr: '', exitCode: 0 };
+  return {
+    stdout: String(result?.stdout || ''),
+    stderr: String(result?.stderr || ''),
+    exitCode: Number.isInteger(result?.exitCode) ? result.exitCode : 0
+  };
 }
 
 async function runOfficialCli(args, options = {}) {
@@ -91,9 +143,19 @@ async function runOfficialCli(args, options = {}) {
       throw new AlipayWalletError('ALIPAY_BOT_NOT_INSTALLED', '未找到支付宝官方钱包工具。请先在当前 Agent 环境安装并授权 @alipay/agent-payment。');
     }
     if (error?.killed || error?.signal === 'SIGTERM') {
-      throw new AlipayWalletError('ALIPAY_WALLET_TIMEOUT', '支付宝钱包等待确认超时；不要据此判断付款失败，请查询订单状态。');
+      throw new AlipayWalletError('ALIPAY_WALLET_TIMEOUT', '支付宝钱包等待确认超时；请用同一支付命令的 status 查询状态。');
     }
-    throw new AlipayWalletError('ALIPAY_WALLET_COMMAND_FAILED', '支付宝钱包未完成该操作。');
+    // The official buyer CLI can use a non-zero process exit for a user-action
+    // state such as “payment pending”. Preserve this invocation's output for
+    // the caller to parse before classifying it as a real command failure.
+    if (Number.isInteger(error?.code)) {
+      return {
+        stdout: String(error.stdout || ''),
+        stderr: String(error.stderr || ''),
+        exitCode: error.code
+      };
+    }
+    throw new AlipayWalletError('ALIPAY_WALLET_COMMAND_FAILED', '支付宝官方钱包未完成该操作。');
   }
 }
 
@@ -104,10 +166,101 @@ function walletStateFromOutput(stdout, stderr) {
   return enabled ? 'ready' : unavailable ? 'unavailable' : 'unknown';
 }
 
-/**
- * Runs only the official local wallet client. It never returns Payment-Needed,
- * Payment-Proof, or raw wallet output to an Agent caller.
- */
+function queryCredentialFromOutput(output) {
+  const tradeNo = output.match(/(?:"tradeNo"|trade\s*no|交易(?:流水)?号)\s*[":：=]\s*["']?([A-Za-z0-9_-]{8,128})/i)?.[1] || null;
+  const outShakeNo = output.match(/(?:"outShakeNo"|out[_ -]?shake[_ -]?no|外部(?:摇一摇)?编号)\s*[":：=]\s*["']?([A-Za-z0-9_-]{8,128})/i)?.[1] || null;
+  return tradeNo ? { type: 'trade_no', value: tradeNo } : outShakeNo ? { type: 'out_shake_no', value: outShakeNo } : null;
+}
+
+function paymentStatusFromOutput(stdout, stderr) {
+  const output = `${stdout}\n${stderr}`;
+  const completed = /支付(?:已)?成功|交易成功|支付已完成|payment\s+(?:was\s+)?(?:successful|completed)|(?:resource|资源).*(?:obtained|success|成功)/i.test(output);
+  const pending = /支付待确认|等待.*确认|待确认|支付处理中|pending(?:\s+confirmation)?|waiting.*confirm/i.test(output);
+  const failed = /支付失败|交易失败|payment\s+failed/i.test(output);
+  return {
+    status: completed ? 'completed' : pending ? 'pending_confirmation' : failed ? 'failed' : 'unknown',
+    credential: queryCredentialFromOutput(output),
+    diagnostic: safeDiagnostic(output)
+  };
+}
+
+function userVisibleWalletOutput(stdout, stderr) {
+  const lines = `${stdout}\n${stderr}`
+    .replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !SENSITIVE_USER_OUTPUT.test(line))
+    .slice(0, 12);
+  return lines.length ? lines.join('\n').slice(0, 1_200) : null;
+}
+
+function walletFailureCode(stdout, stderr, exitCode) {
+  const output = `${stdout}\n${stderr}`;
+  if (/余额不足|insufficient\s+balance/i.test(output)) return 'insufficient_balance';
+  if (/已过期|过期|expired/i.test(output)) return 'payment_expired';
+  if (/钱包.*(?:未开启|未授权)|wallet.*(?:not\s+enabled|not\s+authorized)/i.test(output)) return 'wallet_not_ready';
+  if (/买家.*(?:不匹配|校验失败)|buyer.*(?:mismatch|identity)/i.test(output)) return 'buyer_identity_rejected';
+  if (/账单.*(?:无效|签名)|签名.*(?:无效|失败)|bill.*(?:invalid|signature)/i.test(output)) return 'payment_needed_rejected';
+  if (/network|网络|timeout|超时/i.test(output)) return 'wallet_network_error';
+  return Number.isInteger(exitCode) && exitCode !== 0 ? 'official_cli_nonzero_exit' : 'official_cli_unclassified';
+}
+
+function paymentMessage(status) {
+  if (status === 'completed') return '支付宝钱包显示本次付款已完成；正在由服务端确认权益。';
+  if (status === 'pending_confirmation') return '支付宝已发起本次付款确认；请打开支付宝 App 完成确认，然后运行 status。';
+  if (status === 'failed') return '支付宝钱包显示本次付款未完成；未授予付费 Skill 权益。';
+  return '支付宝官方钱包已被调用，但尚未返回可确认的付款状态；请运行 status 查询，或重新发起付款。';
+}
+
+async function fetchPaymentNeeded(resourceUrl, options = {}) {
+  const fetchFn = options.fetch || globalThis.fetch;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.resourceFetchTimeoutMs || RESOURCE_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetchFn(resourceUrl, {
+      method: 'GET',
+      redirect: 'error',
+      headers: { Accept: 'application/json' },
+      signal: controller.signal
+    });
+    if (response.status === 200) return { alreadyPaid: true };
+    if (response.status !== 402) {
+      throw new AlipayWalletError('ALIPAY_RESOURCE_PAYMENT_NEEDED_FAILED', `支付资源未返回付款请求（HTTP ${response.status}）。`, { status: response.status });
+    }
+    const paymentNeeded = response.headers.get('Payment-Needed');
+    if (!paymentNeeded) {
+      throw new AlipayWalletError('ALIPAY_RESOURCE_PAYMENT_NEEDED_MISSING', '支付资源未返回有效的支付宝付款请求。');
+    }
+    return { paymentNeeded };
+  } catch (error) {
+    if (error instanceof AlipayWalletError) throw error;
+    if (error?.name === 'AbortError') {
+      throw new AlipayWalletError('ALIPAY_RESOURCE_TIMEOUT', '请求支付宝支付资源超时，请重试。');
+    }
+    throw new AlipayWalletError('ALIPAY_RESOURCE_REQUEST_FAILED', '无法请求支付宝支付资源，请检查网络后重试。');
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function publicPaymentResult(state, status, diagnostic, options = {}) {
+  const commandFailed = options.commandFailed === true;
+  return {
+    ok: status !== 'failed' && status !== 'wallet_command_failed',
+    status,
+    provider: 'alipay-agent-payment',
+    attemptId: `alipay-402:${state.resourceDigest.slice(0, 16)}`,
+    walletInvoked: true,
+    message: status === 'wallet_command_failed'
+      ? '支付宝官方钱包没有生成可确认的付款状态；未授予付费 Skill 权益。'
+      : paymentMessage(status),
+    diagnostic,
+    ...(options.userVisible ? { userVisible: options.userVisible } : {}),
+    ...(commandFailed ? { failureCode: options.failureCode || 'official_cli_nonzero_exit' } : {})
+  };
+}
+
+/** Runs only the official local wallet client and never exposes its raw output. */
 export async function checkAlipayWallet(options = {}) {
   const { stdout, stderr } = await runOfficialCli(['check-wallet'], options);
   const state = walletStateFromOutput(stdout, stderr);
@@ -120,9 +273,23 @@ export async function checkAlipayWallet(options = {}) {
   };
 }
 
+/** Checks that the official buyer CLI is present, without querying wallet state. */
+export async function getAlipayWalletBridgeInfo(options = {}) {
+  const { stdout, stderr } = await runOfficialCli(['--version'], options);
+  return {
+    ok: true,
+    state: 'available',
+    provider: 'alipay-agent-payment',
+    message: '支付宝官方付款桥已可用；付款时将由支付宝 App 请求确认。',
+    diagnostic: safeDiagnostic(stdout || stderr)
+  };
+}
+
 /**
- * Starts one explicit buyer-side 402 payment. The official CLI owns the
- * protocol payload and App confirmation; callers only receive a safe result.
+ * Starts a buyer-side 402 payment according to the official sequence:
+ * request the resource once, preserve its exact Payment-Needed header only in
+ * a private local file, then invoke the official buyer CLI with that file and
+ * a stable session id. No protocol data leaves this module.
  */
 export async function payAlipay402Resource(input, options = {}) {
   if (input?.confirm !== true) {
@@ -130,36 +297,98 @@ export async function payAlipay402Resource(input, options = {}) {
   }
   const resourceUrl = normalizeResourceUrl(input?.resourceUrl);
   const intentSummary = normalizeIntentSummary(input?.intentSummary);
-  const wallet = await checkAlipayWallet(options);
-  if (!wallet.ok) {
-    throw new AlipayWalletError('ALIPAY_WALLET_NOT_READY', '支付宝钱包未开启；请先完成钱包授权。');
+  const resource = await fetchPaymentNeeded(resourceUrl, options);
+  if (resource.alreadyPaid) {
+    const state = (await readPaymentState(resourceUrl, options)) || {
+      version: 1,
+      resourceUrl,
+      resourceDigest: digest(resourceUrl),
+      sessionId: null,
+      paymentNeededPath: null,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+    return publicPaymentResult(state, 'completed', 'resource_already_available');
   }
-  const { stdout, stderr } = await runOfficialCli([
+
+  const paths = statePaths(resourceUrl, options);
+  await ensurePrivateDirectory(paths.directory);
+  await writePrivateFile(paths.paymentNeededPath, resource.paymentNeeded);
+  const state = {
+    version: 1,
+    resourceUrl,
+    resourceDigest: digest(resourceUrl),
+    sessionId: randomUUID(),
+    paymentNeededPath: paths.paymentNeededPath,
+    queryCredential: null,
+    status: 'started',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  };
+  await writePaymentState(state, options);
+
+  const walletInvocation = await runOfficialCli([
     '402-buyer-pay',
+    '--session-id', state.sessionId,
+    '--file', state.paymentNeededPath,
     '--resource-url', resourceUrl,
     '--intent-summary', intentSummary
   ], options);
-  return {
-    ok: true,
-    status: 'submitted',
-    provider: 'alipay-agent-payment',
-    attemptId: `alipay-402:${digest(`${resourceUrl}\n${intentSummary}`)}`,
-    message: '已交给支付宝钱包处理；请在支付宝 App 中确认本次付款。',
-    diagnostic: safeDiagnostic(stdout || stderr)
-  };
+  const result = paymentStatusFromOutput(walletInvocation.stdout, walletInvocation.stderr);
+  const commandFailed = walletInvocation.exitCode !== 0 && result.status === 'unknown';
+  const status = commandFailed ? 'wallet_command_failed' : result.status;
+  state.status = status;
+  state.queryCredential = result.credential;
+  state.updatedAt = new Date().toISOString();
+  await writePaymentState(state, options);
+  if (status === 'completed') await rm(paths.paymentNeededPath, { force: true });
+  return publicPaymentResult(state, status, result.diagnostic, {
+    commandFailed,
+    failureCode: commandFailed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : undefined,
+    userVisible: ['pending_confirmation', 'completed', 'failed'].includes(status)
+      ? userVisibleWalletOutput(walletInvocation.stdout, walletInvocation.stderr)
+      : null
+  });
 }
 
+/** Queries an existing local payment attempt using the official query credential. */
 export async function queryAlipay402Resource(input, options = {}) {
   const resourceUrl = normalizeResourceUrl(input?.resourceUrl);
-  const { stdout, stderr } = await runOfficialCli(['402-query-payment-status', '--resource-url', resourceUrl], options);
-  const output = `${stdout}\n${stderr}`;
-  const complete = /success|成功|paid|已支付|completed|完成/i.test(output) && !/pending|等待|处理中/i.test(output);
-  const pending = /pending|等待|处理中|confirm/i.test(output);
-  return {
-    ok: true,
-    status: complete ? 'completed' : pending ? 'pending_confirmation' : 'unknown',
-    provider: 'alipay-agent-payment',
-    message: complete ? '支付宝钱包显示付款已完成。' : pending ? '等待用户在支付宝 App 中确认。' : '支付宝钱包尚未返回可确认的付款状态。',
-    diagnostic: safeDiagnostic(stdout || stderr)
-  };
+  const state = await readPaymentState(resourceUrl, options);
+  if (!state?.queryCredential?.value) {
+    return {
+      ok: false,
+      status: 'no_active_payment',
+      provider: 'alipay-agent-payment',
+      walletInvoked: false,
+      message: '没有可查询的本地支付宝付款记录；请重新发起付款，不要把付款凭证粘贴到对话中。',
+      diagnostic: 'payment_state_not_found'
+    };
+  }
+  const queryArg = state.queryCredential.type === 'out_shake_no'
+    ? ['--out-shake-no', state.queryCredential.value]
+    : ['-t', state.queryCredential.value];
+  const walletInvocation = await runOfficialCli([
+    '402-query-payment-status',
+    ...queryArg,
+    '--resource-url', resourceUrl
+  ], options);
+  const result = paymentStatusFromOutput(walletInvocation.stdout, walletInvocation.stderr);
+  const commandFailed = walletInvocation.exitCode !== 0 && result.status === 'unknown';
+  const status = commandFailed ? 'wallet_command_failed' : result.status;
+  state.status = status;
+  state.queryCredential = result.credential || state.queryCredential;
+  state.updatedAt = new Date().toISOString();
+  await writePaymentState(state, options);
+  if (status === 'completed') {
+    const { paymentNeededPath } = statePaths(resourceUrl, options);
+    await rm(paymentNeededPath, { force: true });
+  }
+  return publicPaymentResult(state, status, result.diagnostic, {
+    commandFailed,
+    failureCode: commandFailed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : undefined,
+    userVisible: ['pending_confirmation', 'completed', 'failed'].includes(status)
+      ? userVisibleWalletOutput(walletInvocation.stdout, walletInvocation.stderr)
+      : null
+  });
 }

package/index.mjs

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { ConvexHttpClient } from 'convex/browser';
 import { anyApi as api } from 'convex/server';
 
-export const VERSION = '0.1.11';
+export const VERSION = '0.1.13';
 
 export const DEFAULTS = {
   cn: {
@@ -1361,6 +1361,7 @@ export function stableTaskId() {
 export {
   AlipayWalletError,
   checkAlipayWallet,
+  getAlipayWalletBridgeInfo,
   payAlipay402Resource,
   queryAlipay402Resource
 } from './alipayWallet.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiashe/sdk",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "main": "index.mjs",
   "exports": {