@xiashe/sdk 0.1.29 → 0.1.31

package/alipayWallet.mjs

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { chmod, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import os from 'node:os';
@@ -8,10 +8,18 @@ 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|payguard|validateclientparent|agentfamily/i;
+const SENSITIVE_USER_OUTPUT = /payment[-_ ]?proof|payment[-_ ]?needed|seller_signature|runtimeToken|authorization\s*:|trade[_ -]?no|交易(?:流水)?号|订单号|查询单号|out[_ -]?shake|client[_ -]?session|payguard|validateclientparent|agentfamily/i;
 const DEFAULT_STATE_DIR = path.join(os.homedir(), '.xiashe', 'alipay-402');
 const OFFICIAL_MEDIA_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
 const MAX_OFFICIAL_MEDIA_BYTES = 8 * 1024 * 1024;
+// The buyer CLI documents an AI Pay query number as 32 digits with `8282`
+// in positions 11–14. Merchant out_trade_no values must never be accepted
+// here: they cannot query a buyer-side 402 transaction.
+const OUT_SHAKE_NO_PATTERN = /^\d{10}8282\d{18}$/;
+const WALLET_SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,191}$/;
+const OFFICIAL_WALLET_COMMAND = 'alipay-bot';
+const REQUIRED_BUYER_PAY_OPTIONS = ['402-buyer-pay', '--session-id', '--file', '--resource-url', '--intent-summary'];
+const REQUIRED_STATUS_OPTIONS = ['402-query-payment-status', '--out-shake-no', '--trade-no', '--resource-url'];
 const SAFE_OFFICIAL_FAILURE_CODES = new Set([
   'TRADE_PROGRESS_FAILED',
   'PAYMENT_NEEDED_REJECTED',
@@ -203,6 +211,20 @@ function normalizeResourceUrl(value) {
   return url.toString();
 }
 
+/**
+ * Alipay support may call this a "business order number", but the 402 status
+ * API accepts it only when it has the 32-character outShakeNo shape accepted
+ * by the official client. This is a query credential, not a merchant out_trade_no and never a
+ * Payment-Proof or fulfillment acknowledgement credential.
+ */
+function normalizeOutShakeNo(value) {
+  const outShakeNo = String(value || '').trim();
+  if (!OUT_SHAKE_NO_PATTERN.test(outShakeNo)) {
+    throw new AlipayWalletError('ALIPAY_OUT_SHAKE_NO_INVALID', '业务单号不是有效的支付宝 AI付查询凭证。');
+  }
+  return outShakeNo;
+}
+
 function normalizeIntentSummary(value) {
   const summary = safeText(value, 180);
   if (!summary) {
@@ -211,6 +233,22 @@ function normalizeIntentSummary(value) {
   return summary;
 }
 
+/**
+ * The official buyer CLI binds its payment intent to the active Agent
+ * conversation. A generated UUID is not a valid substitute: it prevents the
+ * wallet from correlating a later confirmation/status query with this task.
+ */
+function normalizeWalletSessionId(value) {
+  const sessionId = String(value || '').trim();
+  if (!sessionId) {
+    throw new AlipayWalletError('ALIPAY_SESSION_ID_REQUIRED', '付款桥接缺少当前 Agent 的业务会话 ID；未请求资源或调用钱包。');
+  }
+  if (!WALLET_SESSION_ID_PATTERN.test(sessionId)) {
+    throw new AlipayWalletError('ALIPAY_SESSION_ID_INVALID', '付款桥接的业务会话 ID 格式无效；未请求资源或调用钱包。');
+  }
+  return sessionId;
+}
+
 function stateDirectory(options = {}) {
   return path.resolve(options.stateDir || process.env.XIASHE_ALIPAY_PAYMENT_STATE_DIR || DEFAULT_STATE_DIR);
 }
@@ -282,7 +320,7 @@ function normalizedRunnerResult(result) {
 }
 
 async function runOfficialCli(args, options = {}) {
-  const command = safeText(options.command || process.env.XIASHE_ALIPAY_BOT_COMMAND || 'alipay-bot', 200);
+  const command = safeText(options.command || process.env.XIASHE_ALIPAY_BOT_COMMAND || OFFICIAL_WALLET_COMMAND, 200);
   if (!command || /\s/.test(command)) {
     throw new AlipayWalletError('ALIPAY_BOT_COMMAND_INVALID', '支付宝钱包命令配置无效。');
   }
@@ -321,13 +359,18 @@ function walletStateFromOutput(stdout, stderr) {
 }
 
 function queryCredentialFromOutput(output) {
-  // The official wallet has used both camelCase and snake_case JSON fields.
-  // Match either spelling without forwarding the raw wallet output.
+  // Current official CLI output labels the preferred status credential as
+  // “订单号” or “查询单号”; it is not the merchant's out_trade_no. Older
+  // wallets used camelCase/snake_case fields, which remain supported here.
+  // Match only the documented, fixed AI Pay shape and keep it in private
+  // state—never return it in bridge output.
+  const labeledOutShakeNo = output.match(/(?:订单号|查询单号)\s*(?:[":：=]\s*)?["']?(\d{32})/u)?.[1] || null;
   const tradeNo = output.match(/(?:["']?trade[\s_-]*no["']?|交易(?:流水)?号)\s*[":：=]\s*["']?([A-Za-z0-9._-]{8,128})/i)?.[1] || null;
-  const outShakeNo = output.match(/(?:["']?out[\s_-]*shake[\s_-]*no["']?|外部(?:摇一摇)?编号)\s*[":：=]\s*["']?([A-Za-z0-9_-]{8,128})/i)?.[1] || null;
+  const structuredOutShakeNo = output.match(/(?:["']?out[\s_-]*shake[\s_-]*no["']?|外部(?:摇一摇)?编号)\s*[":：=]\s*["']?(\d{32})/i)?.[1] || null;
+  const outShakeNo = labeledOutShakeNo || structuredOutShakeNo;
   // An outShakeNo is the preferred 402 status-query credential, but only its
-  // documented 32-character AI Pay form may select that query path.
-  const validOutShakeNo = outShakeNo && outShakeNo.length === 32 && outShakeNo.slice(10, 14) === '8282';
+  // documented 32-digit AI Pay form may select that query path.
+  const validOutShakeNo = outShakeNo && OUT_SHAKE_NO_PATTERN.test(outShakeNo);
   return validOutShakeNo
     ? { type: 'out_shake_no', value: outShakeNo }
     : tradeNo
@@ -343,9 +386,13 @@ function paymentStatusFromOutput(stdout, stderr) {
   // Treat an explicit unsuccessful result as failed so callers retain the
   // normalized failure category instead of misleadingly reporting an unknown
   // wallet state.
-  const failed = /支付失败|交易失败|payment\s+failed|"success"\s*:\s*false|"errorCode"\s*:/i.test(output);
+  // A successful status-query transport can still include the protected
+  // resource's safe ALIPAY_VERIFY_* response. That is a merchant-side proof
+  // verification failure, not an unknown wallet state.
+  const merchantDiagnostic = safeMerchantDiagnosticCode(stdout, stderr);
+  const failed = Boolean(merchantDiagnostic) || /支付失败|交易失败|payment\s+failed|"success"\s*:\s*false|"errorCode"\s*:/i.test(output);
   return {
-    status: completed ? 'completed' : pending ? 'pending_confirmation' : failed ? 'failed' : 'unknown',
+    status: failed ? 'failed' : completed ? 'completed' : pending ? 'pending_confirmation' : 'unknown',
     credential: queryCredentialFromOutput(output),
     diagnostic: safeDiagnostic(output)
   };
@@ -379,6 +426,7 @@ async function officialWalletMedia(stdout, stderr) {
 
 function walletFailureCode(stdout, stderr, exitCode) {
   const output = `${stdout}\n${stderr}`;
+  if (safeMerchantDiagnosticCode(stdout, stderr)) return 'merchant_payment_proof_verification_failed';
   if (/TRADE_PROGRESS_FAILED/i.test(output)) return 'wallet_trade_progress_failed';
   if (/payment[_ -]?needed[_ -]?rejected|账单.*(?:被拒绝|拒绝)|bill.*(?:rejected|denied)/i.test(output)) return 'payment_needed_rejected';
   if (/余额不足|insufficient\s+balance/i.test(output)) return 'insufficient_balance';
@@ -501,7 +549,9 @@ function paymentFailureDiagnosis(failureCode, stdout, stderr) {
 
 function paymentFailureUserVisible(diagnosis) {
   const lines = [
-    diagnosis.code === 'wallet_query_credential_missing'
+    diagnosis.stage === 'merchant_payment_proof_verification'
+      ? '商家未能验证本次支付宝付款凭证，尚未授予付费 Skill 权益。'
+      : diagnosis.code === 'wallet_query_credential_missing'
       ? '支付宝钱包未返回可继续查询的交易凭据，当前付款状态无法确认。'
       : '支付宝付款未创建可确认交易。',
     `诊断代码：${diagnosis.code}`,
@@ -525,6 +575,9 @@ function paymentMessage(status) {
 }
 
 function paymentFailureMessage(failureCode) {
+  if (failureCode === 'merchant_payment_proof_verification_failed') {
+    return '商家未能验证支付宝付款凭证，未授予付费 Skill 权益；请勿重放旧凭证或重复付款。';
+  }
   if (failureCode === 'wallet_query_credential_missing') {
     return '支付宝钱包返回待确认，但未返回可继续查询的交易凭据。无法确认是否已付款，因此不会授予付费 Skill 权益；请勿再次付款。';
   }
@@ -684,10 +737,11 @@ function publicPaymentResult(state, status, diagnostic, options = {}) {
     ...(failed && diagnosis ? { userVisible: paymentFailureUserVisible(diagnosis), diagnosis } : {}),
     ...(!failed && options.userVisible ? { userVisible: options.userVisible } : {}),
     ...(options.officialMedia ? { officialMedia: options.officialMedia } : {}),
+    ...(options.queryCredentialSource ? { queryCredentialSource: options.queryCredentialSource } : {}),
     ...(status === 'pending_confirmation'
       ? { confirmation: { source: 'official_alipay_wallet', surface: 'app_or_official_media', required: true } }
       : { confirmation: { source: 'official_alipay_wallet', required: false } }),
-    ...(commandFailed ? { failureCode } : {})
+    ...(failed ? { failureCode } : {})
   };
 }
 
@@ -706,17 +760,28 @@ 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);
-  const runtimeVersion = safeRuntimeVersion(stdout, stderr);
+  const version = await runOfficialCli(['--version'], options);
+  const buyerPayHelp = await runOfficialCli(['402-buyer-pay', '--help'], options);
+  const statusHelp = await runOfficialCli(['402-query-payment-status', '--help'], options);
+  const runtimeVersion = safeRuntimeVersion(version.stdout, version.stderr);
+  const buyerPayOutput = `${buyerPayHelp.stdout}\n${buyerPayHelp.stderr}`;
+  const statusOutput = `${statusHelp.stdout}\n${statusHelp.stderr}`;
+  const buyerPaySupported = REQUIRED_BUYER_PAY_OPTIONS.every((option) => buyerPayOutput.includes(option));
+  const statusSupported = REQUIRED_STATUS_OPTIONS.every((option) => statusOutput.includes(option));
+  const contractValid = buyerPaySupported && statusSupported;
   return {
-    ok: true,
-    state: 'runtime_available',
+    ok: contractValid,
+    state: contractValid ? 'runtime_available' : 'runtime_incompatible',
     provider: 'alipay-agent-payment',
-    message: '已找到支付宝官方钱包程序；这只表示程序可执行，尚未检查钱包授权或交易资格。',
+    message: contractValid
+      ? '已找到支付宝官方钱包程序，并确认当前买方支付/查询命令参数可用；尚未检查钱包授权或交易资格。'
+      : '支付宝官方钱包程序缺少当前 402 买方支付或查询命令参数；未创建交易。请用官方安装器更新钱包运行时后重试。',
     walletStateChecked: false,
     transactionCreationVerified: false,
+    paymentCommandsValidated: contractValid,
     ...(runtimeVersion ? { runtimeVersion } : {}),
-    diagnostic: safeDiagnostic(stdout || stderr)
+    ...(contractValid ? {} : { failureCode: 'wallet_runtime_contract_invalid' }),
+    diagnostic: safeDiagnostic(`${version.stdout}\n${version.stderr}\n${buyerPayHelp.stdout}\n${buyerPayHelp.stderr}\n${statusHelp.stdout}\n${statusHelp.stderr}`)
   };
 }
 
@@ -732,6 +797,7 @@ export async function payAlipay402Resource(input, options = {}) {
   }
   const resourceUrl = normalizeResourceUrl(input?.resourceUrl);
   const intentSummary = normalizeIntentSummary(input?.intentSummary);
+  const sessionId = normalizeWalletSessionId(input?.sessionId);
   const resource = await fetchPaymentNeeded(resourceUrl, options);
   if (resource.alreadyPaid) {
     const state = (await readPaymentState(resourceUrl, options)) || {
@@ -758,7 +824,7 @@ export async function payAlipay402Resource(input, options = {}) {
     version: 1,
     resourceUrl,
     resourceDigest: digest(resourceUrl),
-    sessionId: randomUUID(),
+    sessionId,
     paymentNeededPath: paths.paymentNeededPath,
     queryCredential: null,
     merchantResource: {
@@ -774,9 +840,9 @@ export async function payAlipay402Resource(input, options = {}) {
   const walletInvocation = await runOfficialCli([
     '402-buyer-pay',
     // The official buyer CLI accepts this long form of -s/-f/-r. The file
-    // name is intentionally private and random; the exact Payment-Needed
-    // content, original resource URL, and generated UUID session are what
-    // define the payment request.
+    // name is intentionally private and random. The exact Payment-Needed
+    // content, original resource URL, and active Agent business session are
+    // what define the payment request.
     '--session-id', state.sessionId,
     '--file', state.paymentNeededPath,
     '--resource-url', resourceUrl,
@@ -821,11 +887,25 @@ export async function payAlipay402Resource(input, options = {}) {
   });
 }
 
-/** Queries an existing local payment attempt using the official query credential. */
+/**
+ * Queries an existing local payment attempt using its official query
+ * credential. Alipay support can also provide a valid outShakeNo (often
+ * called a business order number); that one read-only query does not create
+ * local state, initiate a payment, or acknowledge fulfillment.
+ */
 export async function queryAlipay402Resource(input, options = {}) {
   const resourceUrl = normalizeResourceUrl(input?.resourceUrl);
-  const state = await readPaymentState(resourceUrl, options);
-  if (!state?.queryCredential?.value) {
+  const suppliedOutShakeNo = input?.outShakeNo || input?.businessNo
+    ? normalizeOutShakeNo(input?.outShakeNo || input?.businessNo)
+    : null;
+  if (input?.outShakeNo && input?.businessNo && normalizeOutShakeNo(input.outShakeNo) !== normalizeOutShakeNo(input.businessNo)) {
+    throw new AlipayWalletError('ALIPAY_OUT_SHAKE_NO_CONFLICT', '提供的支付宝查询业务单号不一致。');
+  }
+  const persistedState = await readPaymentState(resourceUrl, options);
+  const queryCredential = suppliedOutShakeNo
+    ? { type: 'out_shake_no', value: suppliedOutShakeNo }
+    : persistedState?.queryCredential;
+  if (!queryCredential?.value) {
     return {
       ok: false,
       status: 'no_active_payment',
@@ -836,9 +916,20 @@ export async function queryAlipay402Resource(input, options = {}) {
       diagnostic: 'payment_state_not_found'
     };
   }
-  const queryArg = state.queryCredential.type === 'out_shake_no'
-    ? ['--out-shake-no', state.queryCredential.value]
-    : ['-t', state.queryCredential.value];
+  const state = persistedState || {
+    version: 1,
+    resourceUrl,
+    resourceDigest: digest(resourceUrl),
+    sessionId: null,
+    paymentNeededPath: null,
+    queryCredential: null,
+    status: 'querying',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  };
+  const queryArg = queryCredential.type === 'out_shake_no'
+    ? ['--out-shake-no', queryCredential.value]
+    : ['--trade-no', queryCredential.value];
   const walletInvocation = await runOfficialCli([
     '402-query-payment-status',
     ...queryArg,
@@ -851,20 +942,24 @@ export async function queryAlipay402Resource(input, options = {}) {
   const officialMedia = ['pending_confirmation', 'completed'].includes(status)
     ? await officialWalletMedia(walletInvocation.stdout, walletInvocation.stderr)
     : null;
-  state.status = status;
-  state.queryCredential = result.credential || state.queryCredential;
-  state.lastFailureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : null;
-  state.lastDiagnosis = failed
-    ? paymentFailureDiagnosis(state.lastFailureCode, walletInvocation.stdout, walletInvocation.stderr)
-    : null;
-  state.lastWalletDiagnostic = result.diagnostic;
-  state.updatedAt = new Date().toISOString();
-  await writePaymentState(state, options);
-  if (status === 'completed') {
+  const failureCode = failed ? walletFailureCode(walletInvocation.stdout, walletInvocation.stderr, walletInvocation.exitCode) : undefined;
+  if (persistedState) {
+    state.status = status;
+    // A support-supplied outShakeNo is used only for this invocation. Never
+    // replace or persist a local query credential with it.
+    state.queryCredential = suppliedOutShakeNo ? state.queryCredential : result.credential || state.queryCredential;
+    state.lastFailureCode = failureCode ?? null;
+    state.lastDiagnosis = failed
+      ? paymentFailureDiagnosis(failureCode, walletInvocation.stdout, walletInvocation.stderr)
+      : null;
+    state.lastWalletDiagnostic = result.diagnostic;
+    state.updatedAt = new Date().toISOString();
+    await writePaymentState(state, options);
+  }
+  if (status === 'completed' && persistedState) {
     const { paymentNeededPath } = statePaths(resourceUrl, options);
     await rm(paymentNeededPath, { force: true });
   }
-  const failureCode = failed ? state.lastFailureCode : undefined;
   return publicPaymentResult(state, status, result.diagnostic, {
     commandFailed: failed,
     failureCode,
@@ -872,7 +967,8 @@ export async function queryAlipay402Resource(input, options = {}) {
     userVisible: ['pending_confirmation', 'completed'].includes(status)
       ? userVisibleWalletOutput(walletInvocation.stdout, walletInvocation.stderr)
       : null,
-    officialMedia
+    officialMedia,
+    ...(suppliedOutShakeNo ? { queryCredentialSource: 'supplied_out_shake_no' } : {})
   });
 }
 

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.29';
+export const VERSION = '0.1.31';
 
 export const DEFAULTS = {
   cn: {

package/package.json

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